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Re Internals Documentation 
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Attatched is the first draft of the Lise Developrnernt System Internals Docurnentation 
Please note that this is a living document; changes wil] be made, and no part of it is 
quarerteed to be accurate. If you have any changes or corrections, PLEASE don't just 
mark them in your copy; tell me about thern. Suggestions for inclusions in the next 
release are also welcome. 


Preface 


The purpose of this document is to explain the internal structures and algorithms used 
by the Lisa's run-time environment and development tools, and the internal library 
units (such as OBJIOLIB and SULIB) that are related only to Lisa systerns software. It 
is actually a collection of documerts and memos, any of which can be used 
seperately, all relating to different aspects of the system. 
This is @ reference document for programmers working on the following: 

» Maintaining or enhancing existing Lisa development software. 


« Writing compilers or utilities for the Lisa Workshop, either on contract with Apple 
or as third-party independants. 


« Writing assembly-language programs that will interface with our cornpiled code. 


How will they benefit from this document? 


= It will save the people maintaining tools the trouble of looking through the code 
themselves to find information. 


= It will save outside programmers, who don't have access to the code, from calling 
us to ask questions about things that we have to look up in the code. 


* Parts of it will be included as a reference section in technical contracts that we 
assign to outside programmers. 


« It will provide assembly-language programmers with such specifics as register 
conventions, pararneter-passing techniques, and memory layouts used by the 
compiler for different types of arrays and structures. 


« It can be used to train new systerns software programmers on the existing internals 
of the system. 
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Lisa Development Software 
Documentation: 
A Road Map 


Introduction 


This road map was designed to help you to find your way sround the verious 
documents describing program developrnent for the Lisa. It will help you decide 
which software you need to learn more about, which software you can ignore for the 
moment, and how you should proceed in studying the rest of the technical 
documentation. 


General Overview of the Environmerts Available 


There are as many ways of writing programs as there are creative programmers. 
However, Apple supports only three general styles of programs that you can write for 
the Lisa: those written for 1) the Workshop environment, 2) the QuickPort 
environment, and 3) the ToolKit environment. Programs written for any of these 
environments can use most of the same units and libraries, but there are some 
importart differences of which you should be aware. 


The tVvorkshop (Figure 1) provides a simple non-window, character and graphic 
ervironment within which a program may run. Programs written to run in this 
environment may use Pascal's built-in I/0 for both files and textual display to the 
console's terminal emulator, or they may directly utilize the Lisa OS's file system 
primitives. They may also use the QuickDraw unit for drawing bitmap graphics and 
displaying text in a variety of fonts with various attributes, and may utilize a variety 
of other useful library routines. These programms are not able to use the Lisa Desktop 
libraries dealing with windows, menus, and dialog boxes, nor do they have easy access 
to Lisa Office System documents. 


In addition to providing these run-time facilities, the Workshop also includes 46 
commend shell which makes available to users an extensive set of facilities for: 1) 
Interactive program development in Pascal, Assembly, BASIC, and COBOL; 2) File and 
device manipulation, and 3) Interactive and batch program execution and control. 


guickFort (Figure 2) provides the simplest Desktop ervironmert, et least from the 
programmer's viewpoint. In most respects, writing @ program for the QuickPort 
environment is identical to writing one for the Workshop environment. Using Pascal's 
built-in 1/0 facilities, programs written for QuickPort may do textual display to a 
veriety of window-based terminal ermulators, and may also display graphics using 
QuickDraw. These programs do not directly use the Lisa Desktop libraries, and are, in 
fact, unawere of such things as the window environmert, the mouse, and menus. They 
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may, however, exchange information with Lisa Office Systerm documents via the 
Cut/Paste mechanism. 


The Toolkit (Figure 3) provides the most complete access to the Desktop facilities. 
From the prograrnmer's viewpoint, it also requires the most knowledge of these 
facilities. Programs written using the ToolKit use the Generic Application and may 
use any of the ToolKit building blocks, which provide easy, controlled access to the 
Lisa Desktop libreries, the mouse, and menus. They may also exchange information 
with Lisa Office System documents via the Cut/Paste mechanism. 


Overview of the Pieces 


; is @ set of units that are USEd and linked with a program which is to be 
run in the Desktop environment. QuickPort then provides the program with a 
“terrninal window", to which the program's console 1/0 may be directed through the 
use of Pascal's built-in Text I/0 facilities. The program simply makes ReadLn and 
WriteLn calls to display text or receive keyboard input. QuickPort code hides frorm 
the program such issues as cutting and pasting information fromm other Desktop 
applications, communicating with the Desktop shell, growing and shrinking the window, 
covering and uncovering the window, and activating or deactivating the program. For 
@ program using QuickPort, such issues ere of no concern. 


The fookK# is a set of libraries that provides standard Lisa application behavior, 
including windows that can be moved, resized, and scrolled, pull-down menus with 
standard functions such as saving and printing, and the Cut/Paste mechanism. The ( 
ToolKit defines the parts of an application common to all Lisa applications. The 
object-oriented structure of the ToolKit allows you to implement your application as 
extensions to the "Generic Application". 


The isa Qperating Systern provides the program with an environment in which 
multiple processes can coexist, with the ability to communicate and share data. It 
provides a device-independent file system for 1/0 and information storage, and handles 
exceptions (software interrupts) and memery management for both code and data 
segments. 


PASLIB is the Pascal run-time support library. Most of the routines in PASLIB 
support the Pascal built-in facilities, including routines for initialization, integer 
erithmetic, data and string manipulation, sets, range checking, the heap, and 1/0. 


Floating Poirk Libraries provide numeric routines which implement the proposed IEEE 
Floating Point Standard (Standard 754 for Binary Floating-Point Arithmetic), and 
higher-level mathematical algorithms. FPLib provides Single (32-bit), Double (64-bit), 
and Extended (80-bit) floating-point data types, a 64-bit Integer data type, conversion 
fromm one arithmetic type to another (or to ASCII), arithmetic operations, 
transcendental functions, and tools for handling exceptions. MaethLib provides, among 
others, algorithms such as extra elementary functions, sorting, extended conversion 
routines, financial analysis, zeros of functions, and linear algebra. 


QuickDraw is & unit for doing bit-mapped graphics. It consists of procedures, 
functions, and data types you need to perform highly complex graphic operations very 
easily and very quickly. You can draw text characters in a number of fonts, with 
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variations that include boldface, italic, underlined, and outlined; you can draw 
arbitrary or predefined shapes, either hollow or filled; you can draw straight lines of 
any length and width, or you can draw any combination of these items, with a single 
procedure call. 


The Desktop Libraries provide window, graphics, mouse, and menu routines used by 
all Office System applications. They are not directly called by any programs written 
for the three run-time environments discussed here, but provide the hidden foundation 
for both the QuickPort and the ToolKit environments. 


The Hardware Interface unit lets you access Lise hardware elements such as the 
mouse, the cursor, the display, the contrast control, the speaker, the keyboard, the 
micro- and millisecond timers, and the hardware clock/calendar. 


The Standard Unt lets you do string, character, and file-name manipulation, 
prompting, retrieval of messages frorn disk files, abort exec file processing, and 
conversions between numbers and strings. 


The MFrimitives unit provides you with fast, efficient text-file input and output. 


The Frogram Communication unit allows programs to communicate with each other 
and with the Workshop shell. 


Lisafhag allows you to examine and modify memory, set breakpoints, assemble and 
disassemble instructions, and perform other functions for run-time debugging. 


More Detail 


QuickPort: A program which is to make full use of the capabilities of the Lisa Office 
System will be structured as an endless loop, within which the program continually 
polls the Window Manager for any events it should respond to. We will refer to such 
@ program as an /mtegrated Frogram An integrated program must handle such 
asynchronous events as the program's window being activated or deactivated, the 
window being opened, closed, moved, resized, or needing update, the mouse button 
going down or up, and a key going down or up. The program must also be a good 
citizen in Lisa's multi-tasking but non-preemptive scheduling environment by 
volurteering periodically to yield the CPU to any other process needing service. 
These are just a few of the important cheracteristics of an integrated program. The 
result of a program following these and other guidelines will be that it exhibits the 
same consistent, responsive behavior as other Apple-written programs like LisaDraw. 


GuickFort is a collection of pieces which make writing programs for the Office 
System's window environment as easy as writing them for the Warkshop's non-window 
environment. NOTE: In order to differentiate the QuickPort modules from the 
program which uses them, we will refer to the program itself as a Manilla Program 
QuickPort allows the vanilla program to be more traditionally structured, as if its user 
interfacing were being done through a smart text/graphics terminal; the vanilla 
program presents its display to the user by a combination of text 1/0 calls (e.g., 
WriteLn/ReadLn) and QuickDraw calls (e.g., DrawString/PaintRect). The QuickPort 
modules handle all events from the Window Manager, provide for yielding the CPU to 
competing processes at specific points, and in general shelter the program from the 
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sometimes tricky requiremerts of writing an integrated program for the Lisa Office 
System. 


QuickPort provides the vanilla program with a window, which may be divided into a 
Text Fane] and a QuickDraw Fane! for displaying both textual and graphic 
information. Each of these optional panels is configurable in size and location, and 
may be independently scrolled horizontally or vertically. Text and Graphics windows 
may be overlaid, so the resulting window presents a composite of both types of 
output. The window may be resized, moved, covered, or uncovered without the 
vanilla program even being awere of such events. Textual and graphic information 
may be exchanged between & vanilla program's documert and other documents, 
whether vanilla or integrated, by using the familiar Cut/Paste mechanism. Without 
any effort on the part of the vanilla program, the end user is given a large measure 
of control over the window's configuration and behavior, using mouse and menu 
actions supported by QuickPort. 


The user may request printing of either the text pane) or the graphics panel. In 
addition, vanilla programs may produce printed output under programm control by 
writing to the -PRINTER logical device. Whereas, in the Workshop environment, 
printing is immediete (each line printing as soon as the program "writes" it), in the 
QuickPort/Desktop environment printing is al] spooled. This means that the printed 
output of a vanilla program will be submitted to the Office system's PrintShop, which 
determines from the print queue when the document will be printed. 


The fex? Fanel emulates a terminal display which corresponds to the Pascal built-in 
OUTPUT file, the built-in INPUT file, and the -CONSOLE and -KEYBOARD logical ( 
devices. Apple provides emulators for the K72cx? and SARC terminals, and makes 
it possible for you to either custornize them or create entirely new terminal 
emulators. These terminal emulators are actually /7iters which pre-process the 
character output strearn destined for the Standard Terminal Lint. which provides the 
Text Panel display. Each emuletor's job is to recognize the terminal-specific 
character sequences imbedded in the output stream which ere commands to the 
terminal, and to call upon the Standard Terminal Unit to take the appropriate actions. 
A program may eliminate the filtering step, if desired, by calling directly upon the 
Standerd Terminal Unit for display actions. 


The Graphics Fanel allows your program to display graphics on a bitmap which is a 
maximum of 720 pixels wide by 364 pixels high--the same size as Lisa's physical 
screen bitmap. This panel can be resized by the user or under program control, and 
can be scrolled horizortally and vertically to display different perts of the entire 
bitmap. The Graphics Pane] supports every QuickDraw call, including those related to 
setting foreground and background colors for printed output. An application may 
write anywhere in the coordinate plane of its graphics panel (‘grafPort', to use 
QuickDraw's terminology), without having to worry about where its window is placed 
on the screen or what other windows are in front of it. QuickDraw, with a little help 
from the Window Manager, keeps the application's output from getting out of the 
graphics pane] or from clobbering other windows. | 
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The ToolKit: The ToolKit is a set of libraries that provides standard behavior that 
follows the design principles characterizing Lisa applications: 


* Extensive use of graphics, including windows and the mouse pointer. 
» Use of pull-down menus for commands. 

« Few or no operating modes. 

» Data transfer between documents by simple cut and paste operations. 


For example, all Lisa applications have windows thet can be moved around the screen, 
and that can usually be resized and scrolled. The ToolKit takes cere of all these 
functions. The ToolKit also displays a menu ber for the active application, and 
provides a number of standard menu functions, such as saving, printing, and setting 
aside. 


However, the ToolKit is more than a set of libraries. Because the Toolkit is written 
using Clascal, the ToolKit is almost a complete program by itself. You can, in fact, 
write a five-line main program, compile it, link it with the ToolKit, and run it. What 
results is the Generic Application. 


The Generic Application has many of the standard Lisa application characteristics. A 
piece of Generic Application stationary can be torn off, and, when the new documerit 
is opened, it presents the user with a window with scroll bars, split controls, size 
control, and a title bar. The mouse poirter is handled correctly when it is over the 
window. The window can be moved, resized, and split into multiple panes. There is 4 
menu baer with & few standard functions, so that the generic document can be saved, 
printed, and set aside. The single Generic Application process can manage any 
number of documents. You cannot, however, do anything within the window, aside 
from creating panes. The space within the window, along with the additional menu 
fuctions, is the responsibility of the real application. 


Therefore, when you write a Lisa application using the ToolKit, you essentially write 
extensions to the Generic Application. It is very easy to write extensions to any 
Clascal program. To insert your application's functions, you create a set of 
subclasses, including methods to perform the work of you application, and then you 
write @ simple main program, and compile and link it with the Toolkit. 


Whenever necessary, the ToolKit calls your application's routines. For example, if the 
user scrolls the document, the ToolKit tells your program to redraw the changed 
portions of the window. Your program does not need to be concerned with when 
redrawing is required. 


One effect of Clascal is that you can write applications in steps. You can begin by 
doing the least amount possible, and get an application that does very little, but wil) 
run. You can then extend your application bit by bit, checking as you go. This 
characteristic of Clascal makes it easy to extend the capabilities of ToolKit programs, 
even years efter the original program. 


The ToolKit's debugger, KitBug, provides run-time debugging of ToolKit Clascal 
programs. It allows you to do performance measurements, set breakpoints and traces, 
single-step through your program one stetement et a time, and do high-level 
examinations of data objects. . 
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The Operating System: The Operating Systerm provides an environment in which 
multiple processes can coexist, with the ability to communicate and share data. It 
provides a file system for I/0 and information storage, and handles exceptions 
(software interrupts) and memory management. 


The File Systerm provides input and output. It accesses devices, volumes, and files. 
Each object, whetner a printer, disk file, or any other type of object, is referenced by 
a pathname. Every 1/0 operation is performed as an uninterpreted byte stream. Using 
the File System, all 1/0 is device-independent. The File System also provides device- 
specific control operations. 


A process consists of an executing program and the data associated with it. Several 
processes can exist at once, and wil) appeer to run simultaneously because the 
processor is multiplexed among thern. These processes can be broken into multiple 
segments which are automatically swapped into memory as needed. Communication 
between processes is accomplished through events and exceptions. An éevert is 6 
message sent from one process to another, or from a process to itself, that is 
delivered to the receiving process only when the process asks for it. An exception is 
@ special type of event that forces itself on the receiving process. In addition to a 
set of systern-defined exceptions (errors), such as division by zero, you can use the 
systern calls provided to define any other exceptions you want. 


Memory managernent routines handle data segments and code segments. A data 
segment is a file that can be placed in memory and accessed directly. A code 
segmerm is a swapping unit that you can define. If a process uses more memory ( 
than the aveilable RAM, the OS will swap code segments in and out of memary as 
they are needed. 


PASLIB: PASLIB is the Pascal run-time support library. It provides the procedures 
and functions that are built into the Pascal language, acts as the run-time interface 
to the Operating System, and "completes" the 68000 instruction set by providing 
routines for the compiler-generated code to call upon in lieu of actual hardware 
instructions. 


PASLIB routines are called with all parameters passed on the stack. There is an 
initialization routine to initialize necessary variables, libraries, and exception—handlers 
and set up global file buffer addresses, and a termination routine to kill processes. 
You can do four-byte integer srithmetic. Data can be moved, or scanned for a 
particuler character. String manipuletion routines include concatenating, copying, 
inserting or deleting a substring, determining the position of a substring, and 
comparing strings for equality. Set manipulation routines let you find set 
intersections or differences, adjust the size of a set, and cornpare sets for equality. 
There are range-checking and string renge-checking routines. Heap routines let you 
allocate memory in the heap, mark or release the heap, check available memory in 
the heap, and check the heap result. 1/0 routines let you read and write lines, 
characters, strings, packed arrays of characters, booleans, and integers, as well as 
check for a keypress or an end-of-line, and send page marks. File I/O routines 
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include rewriting, resetting or closing a file, detecting an end-of-file, reading and 
writing blocks, and get, put, and seek procedures. 


Floating-Point Libraries: The Lisa provides arithmetic, elernentary functions, and 
higher level mathematical algorithms in its intrinsic units FPLib and MathLib, which 
are contained in the file JIOSFPLIB. 


FPLib provides the sarne functionality as the SANE and Elems units on the Apple } [ 
and ///, including: 


e Arithmetic for all floating-point and Comp types. 

« Conversions between numerical types. 

« Conversions between numerical types, ASCII strings, and intermediate forms. 
« Control] of rounding modes and numerical exception handling. 

« Common elementary functions. 


MathLib provides the extra procedures available only on the Lisa: 


e Extra environments procedures. 

e Extra elementary functions. 

»s Miscellaneous utility procedures. 

© Sorting. 

» Free-formeat conversion to ASCII. 

« Correctly rounded conversion between binary and decimal. 
« Financial analysis. 

e Zeros of functions. 

=» Linear algebra. 


QuickDraw: Virtually all of Lisa's graphics are performed by the QuickDraw unit. 
You can draw text, lines, and shapes, and you can draw pictures combining these 
elements. Drawing can be done to many distinct “ports" on the screen, each of which 
is & complete drawing environment. You can "clip" drawing to arbitrary areas, so 
thet you only draw where you want. You can draw to an off-screen buffer without 
disturbing the screen, then quickly move your drawing to the screen. 


7ext characters are avilable in a number of proportionally-spaced fonts. Any font 
can be drawn in any size--if a font isn't available in a particular size, QuickDraw 
will scale it to the specified size. You can draw characters in any combination of 
boldface, italic, underlined, outlined, or shadowed styles. Text can be condensed or 
extended, and it can be justified (aligned with both a left and a right margin). 


Straight Jines can be drawn in any length and width, and can be solid-colored (black, 
white, or shades of gray) or patterned. 


Shapes defined by QuickDraw are rectangles, rectangles with rounded corners, full 
circles or ovals, wedge-shaped sections of circles or ovals, and polygons. In addition, 
you can describe any erbitrery shape you want. All shapes can be drawn either 
hollow (just an outline, which has all the width and pattern characteristics of other 
lines) or solid (filled in with a color or pattern that you define). 
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QuickDraw lets you combine any of these elements into a picture, which can then be 
drawn--to any scale--with a single procedure call. 


Three-dimensional graphics cepabilities are also available, in a unit called Graf3D, 
which is layered on top of the QuickDraw routines. Graf3D lets you draw three- 
dimensional objects in true perspective, using real variables and world coordinates. 


The Hardware Interface: The Hardwere Interface unit lets you access Lisa hardware 
elements such as the mouse, the cursor, the display, the speaker, the keyboard, and 
the timers and clocks. 


Adouse routines determine the location of the mouse, set the frequency with which 
software knowledge of the mouse location is updated, change the relationship between 
physical mouse movernent and the movemerit of the cursor on the screen, and keep 
track of how far the mouse has moved since boot time. 


Cursor routines let you define different cursors, track mouse movements, and display 
@ busy cursor when an operation takes a long time. 


Screen-cormroi routines can set the size of the screen, and set cortrast and 
automatic fading levels. 


Speaker routines allow you to find out and set the speaker volume, and create 
sounds. 


Routines ere provided to handle the different Ae;boarcs available for the Lisa, as 
well as the mouse button and plug, the diskette buttons and insertion switches, and 
the power switch. You can find out which keyboard is attached, and set the systern 
to believe that a different physical keyboard is connected. You can check to see 
what keys (including the mouse button) sre currently being held down, look at or 
return the events in the keyboard queue, and read and set the repeat rates for 
repeatable keys. 


Date and time routines let you access the microsecond and millisecond timers and 
check or set the date and time. 


The Standard Unit: The Standard Unit (StdUnit) is an intrinsic unit providing a 
number of standard, generally-useful functions. The functions ere divided into areas 
of functionality: character and string manipulation, file name manipulation, prompting, 
retrieval of error messages from disk files, Workshop support, and conversions. 


The unit provides types for standerd strings and for sets of characters, definitions for 
@ number of standard characters (such as <CR> and <BS>), and procedures for case 
conversion on characters and strings, trimming blanks, and appending strings and 
characters. 


File narne manipulation functions let you determine if @ pathnarne is a volume or 
device name only, add file narne extensions (such as ".TEXT"), split a pathname into 
its three basic components (the device or volume, the file name, and the extension), 
put the components back together into a file name, and modify a file name given 
optional defaults for missing volume, file, or extension components. 
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Prompting procedures let you get characters, strings, file names, integers, yes or no 
responses, and so forth from the corisole, providing for default values where 
appropriate. 


Special Workshop functions let you stop the execution of an EXEC file in progress, 
find out the name of the boot and current process volumes, and open system files, 
looking at the prefix, boot, and current process volumes when trying to access 4 file. 


Conversion routines let you convert between INTEGERs (or LONGINTs) and strings. 


The IDPrimitives Unit: The l0Primitives unit provides you with fast, efficient 
text-file input and output routines with the functionality of the Pascal 1/0 routines. 
It includes routines for reading characters or lines, and for writing characters, lines, 
strings, and integers, plus the low-level routines on which the others ere based. 


The Program Communications Unit: The Program Communications unit (ProgComm) 
provides three mechanisms for communication between one program and another or 
between a program and the shell. The first two involve strings sent from 4 program 
to the shell; one tells the shell which program toa run next, the other is 4 "return 
string" that can be read by the exec file processor to tell an exec file, for example, 
whether the program completed successfully. The third rnechanism involves reading 
from and writing to a 1K byte communications buffer, global to the Workshop. Using 
the unit, a program can invoke another program and provide its input through the 
buffer, without user intervention. 


LisaBug LisaBug provides commands for displaying and setting memory locations and 
registers, for assernbling and disassembling instructions, for setting breakpoints and 
traces to trace program execution, for manipulating the memory management 
hardware, and for measuring execution times using timing functions. Utility 
commands are also available to clear the screen, print either the main screen or the 
LisaBug screen, change between decimal and hexadecimal, change the setting of the 
NMI key, and display the values of symbols. 
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Where to Go from Here 


The Lisa development software is not fully documented yet. The following is 4 list of 
what is available, sorne of it only internally, as of this publication. Note that the 
spring-releasé manuals will be organized differently fromm the current versions, and 
will incorporate much of the inforrnation that is now in the internals documentation 
or in separate docurmerts. 


Fascal Reference NMamuuai for the Lisa 
includes: QuickDraw 
Herdwere Interface 
Floating-Point Library 


Operating Swsterm Heference Manuel for the Lisa 
Workshop Liser’s Guide for the Lisa 


2isa Levelopinerk’ System internals Documentation 
includes: Pascal Run-Time Library 
Standard Unit 
LisaBug 
Floating-Point Libraries 


wuickFort Aoplications User Guide* 

QuickFort Frogramrmner'’s Guide* 

An Irtroduction to Ciascal | 
Clascal Self-Stua: 
Toolkit Reference Manuai 

ToolKit Training Segments 


Numerics Manual: A Guide to Using the Apple & Pascal SANE and Elems Units 
FPLib provides the sarne functionality as these units. 


Mathlio Guide* 


*These manuals currently in rough draft form. 
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Figure i 
The Workshop Run-Time Environment 


KEY to Figures 1, 2, & 3 


Cit he OD ——————— 
Description of what it does indicates options] units that may be used 
tt refi 


Floed Map-1i 


ror seereEe EEE 
MICO TEE LEE LLL @VICKPORT PROGRAM seetrittitith 
TOTO SGGGESSSRRRERREROSEERY, 


__(Cimargron tee), | 


IEEE Numerics, Math Algorithms 


Clocks, Speaker 


Strings, Prompts, Error Msgs, misc 


Pascal Run-Time Library 


1/0, Heap, Strings, Math 


Virtual-Terminal Window . 


Generic Application, Bldg Blocks 


Desktop Libraries 


Window Mgr, Storage Mgr, Font Mgr, Print Mor 


Bit-Map Graphics 


Co ee ee Ce OTOH TERRE OOOO EH EE HEH TEH EHTEL EEO EEE SEE OLD Oe eH eS eases 
SOOO HOOT HE ODEO HEE THEE EEOHEHHOHHHSEEESEHHH OHH REET EEEEOS 


Re TT i i na he tere hil cee dn sthladnate be ECT 
20.0 06 08 08000680 0008 66880 00 in nn nw nk oe on nace cccck clk ckk nk oc tc cco nck atte etet te tetetstetete 2.2 .9.0.0 2008 00 50 2 8 
loner erer eo ere care erent eet e eee tO eee eee ee tne Oe T FOO OSS O EOE T ETE H EOE Eee OHO DHEA TE DOSED EOE EE OE EE CORO OE EEOE EOS EEO DEST E OTTO SESE ET SO COS Se 60 e 


Figure 2 
The QuickPart Run-Time Environment ROSE Map- 17 
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Figure 3 
The Toolkit Run-Time Environment 
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Pascal Compiler Directives 


The following compiler commands are available: 


$%+ or $%- 
$C+ or €- 


$D+ or $- 


$£ filename 


$+ or SH 


$I filename 


$L filename 


$t+ or $L- 


/-February-&84 


Allow the % symbol in identifiers. The default is $%-. 


Turn code generation on (+) or off (-). This is done on 6 
procedure-by-procedure basis. These commands should be written 
between procedures; results are unspecified if they are written 
inside procedures. The default is $C+. 


Turn the generation of procedure names in object code on (+) or off 
(-). These cormmands should be written between procedures; results 
are unspecified if they are written inside procedures. The default 
is $D+. 

Start making a listing of compiler errors as they are encountered. 
Arialogous to $L filename (see below). The default is no error 
listing. 


Disables handle checking so dereferenced handles (master pointers) 
may be used in with statements, on the left side of assignment 
statements, and in expressions involving procedure calls. The 
default is $H+. 


Start taking source code from file filename. When the end of this 
file is reached, revert to the previous source file. If the filenarne 
begins with + or -, there must be a space between $I and the 
filename (the space is not necessary otherwise). Files may be $1 
included up ta five layers deep. 


Start listing the cornpilation on file filename. If 6 listing is being 
made already, that file is closed and saved prior to opening the 
new file. The default is no listing. If the filename begins with + 
or -, there must be & space between $L and the filename (the space 
is not necessary otherwise). 


The first + or - following the $L turns the source listing on (+) or 
off (-) without changing the list file. You must specify the listing 
file before using $L+. The default is $L+, but no listing is produced 
if no listing file has been specified. 


Suppress register opitimization (-). The default is $0+. 


Optirnizetion lirnited--use the old (2.0 release) optirnization 
mechanism, instead of the new one. The default is the new one. 


Turn integer overflow checking on (+) or off (-). Qverflow checking 
is dane after all integer add, subtract, 16-bit multiply, divide, 
negate, abs, and 16-bit square operations, and after 32 to 16 bit 
conversions. The default is $0V-. 
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nternsds 


$+ or SR 


$S segnene 


GJ filename 


Gh or FE 


$X+ or $X- 


/-F ebruary- G4 


&@ Confidercis;} 


Turn range checking on (+) or off (-}. At present, range checking is 
done in assignrnent statements and array indexes and for string 
value parameters. No range checking is done for type longint. The 
default is §R+. 


Start putting code modules into segment segname. The default 
segrnent name is @ string of blanks to designate the "blank 
segment," in which the main program and all built-in support code 
are always linked. All other code can be placed into any segment. 


Search the file filename for any units subsequently specified in the 
uses-Clause. Does not apply to intrinsic-units. 


Tell the systern not to search INTRINSIC .LIB for units you use (-). 
The default is $U+ — the system searches INTRINSIC .LIB first, 
then your own libraries. 


Turn automatic run-time stack expansion on (+) or off (-). 
Run-time stack expansion is the insertion of an extra 4-byte 
instruction per procedure to ensure that the Lisa's memory- 
management mechanism has mapped in enough stack space for the 
execution of the procedure. With $X- excessive use of the stack 
by the procedure could cause a bus error. The default is $X+. 


The $SETC command has the form: 


{$SETC ID := DR} 
or ( 
{$SETC ID = EPR} 


where ID is the identifier of a cornpile-time variable and EXPR is a 
compile-tirne expression. EXPR is evaluated immediately. The 
value of EXPR is assigned to ID. 


Compile-time variables ere completely independent of program 
variables; even if a corpile-time variable and & program veriable 
have the sarne identifier, they can never be confused by the 
compiler. 


Note the following points about compile-time variables: 


= Compile-time variables have no types, although their values do. 
The only possible types are integer and boolean. 


» At any point in the program, 4 compile-time variable can have 
a new value assigned to it by a §$SETC command. 
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interneis & Confidertis: 


$IFC, S$ENDC 
$ELSEC Conditional compilation is controlled by the $IFC, $ELSEC, and 

commends, which are used to bracket sections of source text. 
Whether a particuler bracketed section of & program is compiled 
depends on the boolean value of a compile-time expression which 
can contain compile-time variables. 


The $ELSEC and $ENDC commands take no arguments. The $IFC 
command has the forrn: 


{$IFC FR} 
where EXPR is & compile-time expression with a boolean value. 


These three cornmands form constructions sirniler to the Pascal 
if-staterent, except that the $ENDC command is always needed at. 
the end of the $IFC construction. §€LSEC is optional. 


$IFC constructions can be nested within each other to 10 levels. 
Every $IFC must have & matching $ENDC. 


Compile-time expressions appear in the $SETC command and in the 
$IFC cornmand. A cornpile-time expression is evaluated by the 
compiler as soon as it is encountered in the text. 


The only operands allawed in a compile-time expression are: 
« Compile-time variables 


= Constants of the types integer and boolean. (These are also the 
only possible types for results of compile-time expressions.) 


All Pascal aperators are allowed except as follows: 
« The in operator is not allowed. 
«The @ operator is not allowed. 
= The / operator is automatically replaced by div. 
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Fred Forsman 


Revision 1.0 
September 28, 1983 


Remove unsightly, unwanted bytes 
in the privacy of your own office. 


Wo ginmicks, pills. fads or strenuous exercise. 
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PASCAL 
CODE CRUNCHER’S 
HANDBOOK 


Fred Forsman 


Introduction 


This document explains how to reduce the size of Pascal code by changes 
at the Pascal source level. Thus what will be presented are source 
transformations which result in semantically equivalent, but smaller 
code. 


While these transformations will produce smaller code, they are unlikely 
to produce code that is “better” in all senses. Sometimes you will be 
trading off clarity for efficiency since typically you will be changing 
what was the first and obvious way of writing your code. On the other 
hand, your code may benefit (and actually become clearer) just from 
having been thought about a second time. Nevertheless, if it is given 
that you must reduce your code size, you may find these source 
transformations more palatable (and more maintainable) than rewriting in 
assembly language. 


Please note that this is a living document, that is, no claims are made 
that this is a complete or final list of source transformation 
techniques. New techniques will be added as I find out about them (so 
if you are aware of some transformations not mentioned here please let 
me know about them). Also, some of the techniques described will be 
removed from this document when future compiler optimizations obviate 
the need for them. 


Thanks to Al Hoffman for his invaluable assistance in researching and 
documenting much of the material presented here. Thanks also to Ken 
Friedenbach and Rich Page. 
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How to find what code to crunch and how to 
measure your progress 


Given a Pascal unit which you want to crunch, you need to identify the 
procedures which are most likely to benefit from crunching and you need 
@ mechanism by which to measure the results of your efforts. The Pascal 
code generator writes information to the console on the size of the code 
generated for each procedure and the size of the code for the unit being 
compiled. With a compile exec file such as the one below you can 
redirect this information to a file, for use in later analysis. 


SEXEC {perform a compile} 

$ { the first parameter (%O) specifies what file to compile } 

$ { if a second paremeter is specified, it is used for the output obj 
file, otherwise we default to "%O.obj” } : 

$ { if a third paremeter is specified, the code generator's console 
output is redirected to "%2.text", otherwise default to "g.text” } 

3 { the intermediate file is put in a temp file on -parsport } 

P{Pascal }%O 


-paraport-temp 

SIF %2 <> '' THEN 
Gaerne neue Ouen maaan ence 
L 


S{Sys-mgr }O{Out putRedirect}9. text 
SENDIF 


O{quit Sys-moar} 
G{generate}-parsport-temp 
$IF 21 <> '' 

%1 
SELSE 

*D 


SENDIF 

${Sys-mar }0{OutputRedirect }-console 
Of{quit} 

SENDEXEC 


Once you have the code generator's console output, the first step is to 
identify the easy targets for crunching: most often these will be the 
larger routines (code size > 250 bytes, or some similar criterion). The 
above exec file can then be used to verify that any changes you make 
actually result in code size improvements. 
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If you are working on code that is not totally new, chances are that it 
has undergone a number of major and minor changes. As code is modified, 
“dead" code and variables sre often left around inadvertently. These 
unused objects can be discovered and removed by checking the code with 
the various cross reference utilities. (While the Workshop linker will 
remove dead code automatically it will not remove dead variables. ) 


For those of you who want to know what the compiler is realZlj doing, use 
the DumpO0bj utility to look at a disassembly of any of the procedures or 
functions you are interested in. 
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How to crunch code: techniques 


Following are a number of techniques for Pascal source transformation. 
The fine print following the description of each technique attempts to 
estimate the potential space savings, the difficulty of implementation, 
and probability of introducing errors. 


1. 


The first law of code crunching: don't use in-line code when a 
procedure to do the same thing exists. The in-line code may be 
faster, but space is more important in the vast majority of cases. 
In order to apply this lew effectively you should KNOW WHAT IS 
AVAILABLE IN THE LIBRARIES. Similarly you should be femilier with 
what the language provides, particularly in the area of built-in 
procedures and functions. 


Using existing code is pure gain. The danger of doing so should be minimal since the 
compiler end libreries should be error free (or et leest their bugs will be recognized ond 
fixed sooner then your private code which is exercized less often). 


An extension of the above law is the creation procedures which 
perform code sequences which are repeated often in your code (minor 
differences can be handled by paremeterization). One neme for this 
technique is "factoring". Use of paremeters can degrade the 
optimization if the size of the code being factored is small. On 
the other hand, if introduction of a parameter will allow sharing 
of a long sequence of code the extra overhead should be well worth 
it. A word of warning: check to see whether your factoring really 
paid off — the code being factored out should not be smaller than 
the procedure call (and any paremeter passing) that replaces it. A 
point to note is that factoring of even single statements can be 
fruitful, for exemple: 


A[F(X)] := A[LF(X)] + 1; becomes INCA; 


Factoring can be a BIG win in many cases, often saving more than can be achieved Dy any 
other tecnnique. So it often pays to 100k through your code for common code sequences. 
biftiout ty and likelyhood of errors are low, but increase if parameters must be 
introduced . 


Make procedures that are 50-100 lines long - around 300 bytes of 
code - to optimize allocation of variables to register. Shorter 
routines do not have enough occurrences of variables to make 
register allocation worthwhile, and longer routines create more 
opportunities for register optimization than there ere registers 
available. 


The amount of improvenent using this technique is highly variable. Difficulty is 
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4a. 


4b. 


4c. 


4d. 


moderate; likelyhood of errors is low. 


Avoid the use of global scalar (1 to 4 byte) variables whenever 
possible - global variables are never put into registers. 
Techniques applicable here include: 


Assign a frequently used global variable to a local variable, and 
change all references to be the local quantity. Caution! Beware of 
seving and restoring the global quantity around procedure calls 
that might access the global quantity. 


The emount of improvement will be two to four bytes per reference, 
with the greatest gain appearing on assignments like A:=A+1. There 
is an overhead cost to assign the local and save registers (4 to 14 
bytes). Improvement will not occur if the registers have already 
been assigned to locals that are used more frequently than the 
global is. 


The emount of improvenent using this technique is noted shove. Difficulty is low: 
likelynood of errors is high. 


Further leverage on (4a) can be obtained if the seme local 
temporary variable is reused in different parts of the procedure 
for different global variables. In this way, less frequently used 
globals still have a chance for optimization into registers. 


Inprovenent is two or more bytes per @0di tional reference, less 4 bytes eed Ge er 
assigned. Difficulty is moderate; likelynood of errors is even higher then 


Another, more reliable wey of converting 4 global to a local is to 
pass the global variable as a var paremeter to the routine. 
Paremeters are treated like local variables. 


Improvement is two or more bytes per reference, less 8-10 bytes per edditional pareneter, 
sub ject to register competition as noted above. Difficulty end likelyhood of errors vith 
ver parameters is low. 


Move a large main program body into a main subroutine. Move all 
global variables that are only accessed by the main progrem into 
the subroutine. 


Improvement is generally small, since the main program Dody is usually a small part of the 
total code. Difficulty end likelyhood of errors are low. 


In a moderate to large procedure, the number of scalar (1 to 4 
byte) local variables (and parameters) should be kept to a minimum, 
since there is competition for registers. Briefly used integer 
quantities and loop variables, for exemple, should all be stored in 
the seme variable (which might be appropriately named “tempint" or 
some other generic neme). Beware, of course, that the variables 
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( 
usages are never simultaneous. 
Improvenent, for each additional local variable that overloeds en existing register, is 
typically two bytes per reference. Difficulty is low; likelyhood of errors is moderate. 
6. Avoid, at all costs, passing frequently used local variables as var 
paremeters or using them in nested procedures. (Also for 
frequently accessed parameters.) These actions inhibit the value 
from being located in a register. Replace passing aS 4 var 
parameter with assignment to a new local variable, passing the new 
local, then doing 4 reverse assignment. Replace nested procedure 
usage of the variable with passing the variable as a non-var 
paremeter, use of the paremeter inside the subroutine, then, if the 
nested procedure changes the value, copy the parameter into a new 
variable at the end of the subroutine copy it back into the main 
local variable after the call. The following example illustrates 
optimization of nested usage of A and B: 
PROCEDURE UPPER: PROCEDURE UPPER; 
VAR A,B: INTEGER; VAR A,B, TEMP : INTEGER; 
PROCEDURE LOWER; PROCEDURE LOWER( A,B: INTEGER): 
BEGIN BEGIN 
AR := B; comerts to--> A := B; 
TEMP := A 
END END; 
BEGIN BEGIN 
LOWER; LOWER; ( 
{other statements} A := TEM; 
{frequent uses of A and B} {frequent uses of A and B} 
Note that, in the above case, if A is not frequently used in the 
subroutine, it could be eliminated as a parameter and the 
assignment could be made to TEM directly: 
PROCEDURE LOWER(B: INTEGER); 
BEGIN 
TEMP := B; 
END; 
A final added technique that can be used with procedure calls is 
to pass the local as 4 non-ver paremeter, change the procedure to a 
function, and assign the returned function result back to the local 
veriable. 
PROCEDURE PROC(VAR N: INTEGER); FUNCTION PROC(N: INTEGER) : INTEGER: 


PROCEDURE LOCAL; FUNCTION LOCAL(A, 8B: INTEGER) : INTEGER 
Hiad becomes—-~ > oe . 


Pascal Code Cruncher's Handbook Page 7 


10. 


PROC( A} . A 
LOCAL; A 


PROC (A); 
LOCAL (A, B): 


where A is a frequently used local varisble used as a var parameter 
to PROC, and used in nested procedure LOCAL. This method, although 
limited in application, is elegant because no temporary-variable 
assignments have to be inserted. 


Improvement is two or more bytes per reference of the frequently used veriable in the main 
procedure, less 2-8 bytes per extra sssignment statement, subject to register competition 
&s noted above. Since this optimization can be applied to very frequently used varisples 
that are sbendoned by the compiler, large optimizations of up to 40 or more bytes are 
possible in lerge procedures. Difficulty and likelyhood of errors with var persmeter 
substitution is low: difficulty and likelynood of errors vith nested procedures is 
noderate to high. 


Don't use the set construct to check ranges; instead use 
comparisons against the upper and lower bounds. 


Getting rid of the set construct is @ BIG savings (typically around 30 bytes for the usual 
double-ended range check). Oifficulty is mininal, as are the chences of error. 


Do not pass multi-word (more than 4 bytes) data structures as 
non-ver parameters unless necessary. Change them to YAR 
peremeters. 


Improvement is 12-18 bytes saved by not having code to copy the perameter into local 
s tarage in the called procedure. Difficulty is low; likelyhood of errors is moderately 
low 


Replace FOR loops with WHILEs and REPEATs. The equivalent REPEATs 
and WHILEs are typically 8 to 10 bytes shorter, even with the 
explicit loop variable initialization and increments. REPEATS are 
more efficient than WHILES which are better than FORs. Sometimes 
the savings will be greater depending on the contents of the loops 
and the termination condition. 


Swings are typically 8 to 18 bytes per construct. Difficulty and chences of error are 
small (just take care to get your termination condition correct -- bevare of off-by-one 
errors). 


Convert array indexing in loops to pointer arithmetic, when the 
total number of indexing operations can be reduced. For example 


FOR I := 1 T0 100 00 A[I]) -:= 3 comerts to 


P := @A; {A's origin is 1; P is typed as “A[I}} 
FOR I := 1 T0 100 00 

BEGIN 

p* 7s 3; 

P := POINTER(ORD(P)+SIZEOF({A's element type})); 
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11. 


12. 


13. 


14. 


15. 


16. 


17. 


END; 


Improvement is up to 16 bytes per index operation (more when the array origin is nonzero 
or the array element size is not byte; savings cen be even higher on packed structures if 
the progremmer is willing to acd @ few more contortions); difficulty is moderate; 

Lileel yrosod of errors is moderate. 


IFs without ELSE parts that have a conjunctive conditional (IF 4 
AND b THEN ...) are more efficiently expressed as nested IFs (IF a 
THEN IF b THEN ...). In effect, this implements your own ‘short 
circuit" boolean evaluation. 


The savings is typical ly 4 bytes for each AND eliminated. Very easy to implement. Just 
don't try it on ORs 


Avoid packed structures whenever possible. Remember, packing is 
only useful when a large emount of data has to fit in a limited 
space -- it does not decrease the size of the code. 


Improvement is nignly veriable and can be ari Difficulty is low; lLikelynood of errors 
is low if tricks like (10) do not pervade the code. 


Repetition of expressions in the code should be removed by 
pre-assigning a common expression value to a temporary veriable. 


Improvement is highly variable. Difficulty is moderate: likelyhood of errors is low. 


Convert procedure parameters to global or local variables when the 
seme actual value is always passed to the subroutine, and when 
there is no recursion. 


Improvenent is 2-4 bytes per peremeter saved. Severe of creating upleve} addressing of 
‘hot’ veriables however (see (6)). Difficulty is moderate; likelyhood of errors 15 low. 


When groups of local or global variables are commonly passed 
together as paremeters, and are not ‘hot’ (assigned to registers), 
they could be combined into a single record, which would then be 
passed as a var paremeter to the subroutine. 


Inprovenent is 4 bytes per parameter, with an overhead of 8 bytes (warning, the called 


proceoure mey grow in size if it already uses al! registers? Difficulty is mocerate; 
likelyhood of errors is low. 


If you have several instances of the same string constant in your 
code declare it as a CONST, otherwise the compiler will store 
multiple versions of the same constant. 


The savings depends on the size of the string end the number of occurences. Easy to do. 


Turn range checking off after a sufficient emount of testing has 
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occurred. 


Improvement is 4-3 bytes per reference or assignment of @ range-checked quenti ty; 
difficulty is too low; likelyhood of errors is fairly high since a sufficient amount of 
testing never occurs. Consider meking this change on a procecure-bDy-proceaure conricence 
level Desis. 
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How to crunch code: some case studies 


The following section presents some case studies demonstrating some of 
the techniques presented in the previous section. These examples are 
intended to demonstrate how some of the transformational techniques sre 
typically used and how a whole series of transformations may be applied 
to a single body of code. The main purpose of the exemples, however, is 
to give a sense of the thought processes involved in crunching code. 


If you have any good "before" and "after" examples demonstrating how fat 
code was reduced please feel free to contribute them. Your efforts may 
provide ideas and inspiration to others. 


CASE 1: 


Following is the original form of the body of a routine (SUUpCh in the 
StdUnit) which comverts lower case characters to upper case. The code 
size for the original routine was 94 bytes. 


IF Ch IN ['a’..'z'] THEN 
SuUpCh := CHR (ORD (Ch) - 32) 
ELSE 
SUUpCh := Ch; 


The code above was replaced with the following, which replaced the set 
Yange test with two comparisons. The code for this version of the 
procedure was 66 bytes — a savings of 28 bytes (about 30%, or actually 
more, since these sizes include the overhead for the procedure and the 
assignment statements). The moral here is that SET OPERATIONS ARE 
EXPENSIVE . 


IF ('a' <= Ch) AND (Ch <= '2') THEN 
SUUpCh := CHR (ORD (Ch) - 32) 
ELSE 
SUUpCh := Ch; 


The following change was then made which saved another 2 bytes (bringing 
the procedure size down to 64 bytes) by getting rid of the branch for 
the ELSE logic on the IF statement. 


SUUpCh 375 Ch; 
IF (‘a' <= Ch) AND (Ch <= ‘2') THEN 
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SUUpCh := CHR (ORD (Ch) - 32); 


A further change -- breaking the AND in the IF into nested IFs — 
resulted in a 4 byte savings, leaving the procedure size at 60 bytes (an 
improvement of 36% over the original 94 bytes). In effect this is 
performing “short circuit" boolean evaluation at the source level. The 
source for this version is as follows: 


SWupCh := Ch; 
IF ‘a’ <= Ch THEN 
IF Ch <= ‘2' THEN 
SUUpCh := CHR (ORD (Ch) - 32); 


Note that this last transformation would not have worthwhile if we had 
not already removed the ELSE part of the IF since the nested IFs would 
have required two ELSEs. 


CASE 2: 


Below is the body of the original version of SUUpStr which uppercases 4 
string. 


FOR I_:= 1 TO LENGTH (S*) 00 
S*(1] := SuupCh (S*[1]); 


The following version -- converting the FOR loop to a WHILE — saved 8 
bytes. 


I 
WHILE " <= LENGTH (S* ) DO 
BEGIN 
S*(1] := SWpCh (S*[1]); 
I := I] + 1; 
END, 


A further, time-oriented optimization would be to perform the 
upper-casing in reverse order with the call to LENGTH outside the loop, 
which also simplifies the termination condition to a test for zero. 


AN &Side: Wen appropriate (when the loop body will be executed at least once) a REPEAT vill 
seve another 2 bytes. I tested the three constructs with three test procedures (ti, t2, t3) as 
fol lows : 


procedure ti; 
ver 


j.: integer: 
begin 
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for j :s 1 to i do 
foo := ber; 


Jj: integer: 
begin 


23 Der; 
Joi; 


R| 02: 
t >i; 


until j 
T2 (WHILE) saved 8 bytes over Ti (FOR), and T3 (REPEAT) saved 10 bytes over Ti (FOR). 


CASE 3: 


A series of small transformations was applied to the following segment 
of TrimLeading (which trims leading blanks and tabs from a string). 


FOR I := 1 TO ORD (S*[0]) DO 
IF (S*[{I] = SUSpace) OR (S*{I] = SUTab) THEN 
{ skip over leading spaces } 
SE 


BEGIN 
DELETE (S*, 1, I - 1); 
EXIT (TrimLeading); 


{ we fell thru -- either '' or all blanks } 


The first change was to change ORD (S*[0]) to LENGTH (S*), which saved 4 
bytes. (I must have thought I was being clever in the original.) 
Calling the built-in function saves code by leaving the array access to 
the built-in. 


The next change was to get rid of the ELSE in the FOR loop by reversing 
the sense of the condition (which resulted in the code below). This 
last change resulted in no code size change since a short branch was 
removed but another logical operator was added. But this prepared us 
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for some subsequent changes. 


FOR I := 1 TO LENGTH (S*) DO 
IF NOT ((S*[{I] = SUSpace) OR (S*[{I] = SUTab)) THEN 
BEGIN { delete leading as soon as we find & norn-blank char } 
DELETE (S*, 1, I - 1); 
EXIT (TrimLeading): 


END; 
{ we fell thru — either '' or all blanks } 


The next step was to apply de Morgan's lew (remember your boolean 
algebra?) to simplify the conditional to the following form which saved 
2 bytes by reducing the number of boolean operations. 


FOR I := 1 TO LENGTH (S*) 0O 
IF (S*{I] <> SUSpace) AND (S*[I] <> SUTab) THEN 
BEGIN { delete leading as soon as we find a non-blank cher } 
DELETE (S*, 1, I - 1); 
EXIT (TrimLeading); 


END; 
{ we fell thru -—- either ‘' or all blanks } 


Now we have converted the conditional into a form in which we can apply 
our short-circuit evaluation transformation by converting the AND into 
nested IFs, which saves another 4 bytes. 


FOR I := 1 TO LENGTH (S*) 00 
IF (S*[I] <> SUSpace) THEN 
IF (S*{I] <> SUTab) THEN 
BEGIN { delete leading as soon as we find & non-blank char } 
DELETE (S*, 1, I - 1); 
EXIT (TrimLeading): 


END; 
{ we fell thru -- either ‘' or all blanks } 


Finally we convert the FOR construct to a WHILE which saved another 8 
bytes. 


I :2 1; 
WHILE I <= LENGTH (S*) DO 
BEGIN 
IF S*{I] <> SUSpace THEN 
IF S*{I} <> SUTab THEN 
BEGIN { delete leading as soon as we find a non-blank char } 
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DELETE (S*, 1, I - 1); 
EXIT (TrimLeading); 
END; 
I :2 I] + 1; 
END; 
{ we fell thru — either ‘' or all blanks } 


CASE 4: 


The following is applicable only to programs using WRITEs and WRITELNs, 
but the general technique of factoring can be applied anywhere. The 
section of code below prints out the defaults (volume, file neme, and 
extension) for a file neme prompt. 


IF Def¥ol <> ‘' THEN 

WRITE ('[', Def¥ol, ‘] ‘); 
IF DefFN <> ‘'' THEN 

WRITE ('[', DefFN, '] '); 
IF DefExt <> '' THEN 

WRITE ('[{', Def€xt, ‘} ‘); 


The following factoring out of the expensive WRITE operations resulted 
in a savings of 168 bytes. 


PROCEDURE WriteDefault (DefaultValue : SUStr); 
BEGIN 
IF DefaultValue <> ‘' THEN 
WRITE ('[', DefaultValue, '] '); 


? 


WriteDefault (DefVol); 
WriteDefault (DefFN); 
WriteDefault (DefExt); 


CASE 5: 


“Factoring” of common code does not always pay off. Following is an 
instance of how space was saved removing factoring. The SUStrToInt 
conversion routine had an internal procedure called BogusNumber which 
set the value of the CState paremeter to the appropriate error return 
code and then exited from SUStrToInt: 


PROCEDURE BogusNumber (CS : ConmvwNState); | 
BEGIN 
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CState := G; 
EXIT (SUStrToInt); 


é 


BogusNumber was called 6 times in the original SUStrToInt. By replacing 
the calls to BogusNumber with BEGIN CState := ErrCode; EXIT(SUStrToInt) 
END we got rid of the 50 byte BogusNumber routine and the size of 
SUStrToInt when down from 500 bytes to 38 bytes, a total saving of 170 
bytes. The moral here is to CHECK YOUR FACTORING TO SEE THAT IT REALLY 
PAYS OFF. 


The Last Whole Earth 
Text File Forrmat 


Fred Forsman 


This is the latest proposal for the definition of text files. In creating 
this definition I had three (not always convergent) goals in mind. 


1) Text files should support Pascal's model of files of type 
TEXT as well as passible -- that is, if a file was 
written by Pascal WRITES and WRITELNs it should be a 
valid text file with as few exceptions as possible. 

The intent here is to give reasonable SUpDOY t to Pascal's TEXT mechanism as 
it 1s defined in the language -- while the leriquage makes no statement stout 
the form of TEXT files, one would expect thet files written without errors 
Will result in valid text files of some sort. This is not to Soy that 311 
taols snould s Tt every perverse file that can be generated vis Peccal 
text 170. At & MiniMunM, however | the Pascal run-time sys ten should be as 
accomodating s¢ possible in its suppor t of Pascal TEXT 1/0, and the editor 


should should make similar efforts since it is the device most often used to 
inspect text files (whether normal or sberrarit) . 


2) To make the processing of text files as straightforward 
and efficient as possible. 


3) To be compatible with the UCSD text file formats in the 
Pascal systems on the Apple II and Apple ///. 
The following definition follows the UCSO text file format fairly closely. 
Thr one or tyvo Geviatione don't pose & Very serious threat to compatibility 


Since they involve abnormal cases which are not likely to be encountered or 
generated in normal practice. 


The following definition involves compromises to all of the above goals. The 
determination of which goal has been most violated I leave as an exercise t 
the reader. 


The definition of a text file: 
«e A text file is a sequence of 1024-byte pages. 


» Qne 1024-byte header page is present at the beginning of 
the file. This is not considered to be part of the 
actual contents of the text file, but is used by the 
editor to store formatting information, etc. Anyone 
creating a header page should do so with nulls in all 
1024 bytes, unless there is a good reason to do 
otherwise. (The format and interpretation of the header 
page will be described in a forthcoming document.) 
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Each text page (i.e., those following the header page) 
contains some number of Complete lines of text and is 
filled with null characters (ASCII 0) after the last 
line. 

The Pascal run-time system should ensure that all text files end with @ CR 
when CLOSE, in par ticular, dealing with the case where the last ection 
before the CLOSE was a WRITE instead of @ WRITELN. Similarly, the run-time 
system should also ensure that pages terminate with CRs even if inordinately 
10ng lines. are writter: bY & ceries of WRITES without ery WRITELNS. (however 


Getermining when to insert a CR can be @ tricky issue). (For more on 
related issues, see the following two points.) 


» The end of a text page must terminate with at least one 
null. For simplicity, the first instance of a CR-null 
sequence will signal the end of the page. 

RE & consequence of this simplifying assumption. @ WRITELN followed by 3 


WRITE (CHR (0>> will insdvertently terminate the current page, but anyone 
writing nulls to a text file is living in a state of sin and deserves what 


they get. 


To be on the safe side, code dealing with text files at the BLOCKREAD level 
should not assume that a final CR-null always exists, making sure not to run 
off the end of page buffers. Gur tools should not blow up on invalid input. 


® f line is & sequence of zero or more characters followed 
by a ZRO A line may be “arbitrarily long" (1023 bytes 
long, counting the CR. with room for a terminating null 
at the end of the page) but programs (such as development 
system tools) may choose to consider as significant only 
the first A characters ph Nis a reasonable and well 
documented mumber, i.e., either 132 or 255). 
The Pascal run-time system should allow the reading end writing of 
arbitrarily long lines. The contents of @ long line should be obteinable 
Vie @ series of READS. The action of READLN should be to read past the next 


CR. returning en IORESULT warning value if characters are skipped in the 
process . 


Support of “arbitrarily long” lines should not be viewed as a threat to tool 
implementors. Tools may nave reasonable restrictions on what text files 
they choose to accept, a5 long ss they don't Dlow up on other text files. 
Tools may choose to ignore the excess on unreasonably long lines, give 4 
warning, or Signal an error and abort processing. 


«= A sequence of spaces at the beginning of 6 line mai be 
compressed into a two-byte code, namely a 2l& character 


(ASCII 16) followed by a byte containing 32 plus the 
number of spaces represented. 


= A null text file (i.e., one which has no contents -- as 
might be created by opening a file and then closing it 
before anything is written to it) consists of only the 
1024-byte header page. 
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Pascal's Packing Algorithm 


Packed Records 


Packed records are very expensive in terms of the number of bytes of code 
generated by the compiler to reference a particular field. In general, you 
should avoid packing records unless there will be many more instances of the 
record than there sre references to it. Packed records are packed in the 
following bizarre way: 


1. Fields are packed as tightly as possible without crossing word boundries, 
starting at the low-ordered bit of the first byte. (Note that in a 
packed record, a character or 0..255 fits into a byte.) Records will 
always occupy either one byte or an even number of bytes. 


Note that only scalar values and subranges ere considered packable; 
everything else must go on @ word boundry. 


For example, 4 booleans and 4 set are packed as follows: 


Byte 1 BYTE 3 
COOGEE) COCO tote} COT 


2. Any wie bytes are filled by moving the previous field into. the empty 
byte if 


- The field fits into a byte. 
- The field was not previously on a byte boundry. 


? eve 1 0 ? BE Zg 2 BYTE 3 0? BYTE 4 0 
TUT sles] LEE TTT) Cost |] CLIT LITT 


3. Any field that fits in a byte or word and does not share that space with 
other fields is now designated "unpacked". 


Any field that is still considered "packed," and is closest to the high 
end of a byte or word, is moved to the high end of that space. 


? evTe 1 0 ? evTe 2 o 7 BYTE S 0 ? BYTE 4 o 
TTT Teh) LITT) LTT] LITT 

4. The last field is treated after steps 2 & 3 have been completed on the 
other fields. 
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5. Finally, bytes containing packed fields are flipped (bits reordered). 
> Byte 1 0? BYTE 2 0°? BYTE 3 0? BYTE 4 6 
Ja TTTTTs) CLIT) (TT set} CLOTTTTT} 


The following is a (slightly) simpler description of what appears to happen 
when packed records are packed, if you don't need to know the actual process. 


1. Fields are packed as tightly as possible without crossing word boundries, 
starting at the high-ordered bit of the first byte. 


All packed records take up either one byte or an even number of bytes. 


Only boolean or subrange types can be packed; al] other types start on 
word boundries, so steps 2 and 3 only apply to these types. 


2. If a byte would be left empty (so the next field can start on a word 
boundry), and there is more than one field in the previous byte, the last 
(low-ordered) field is moved into the empty byte. 


3. The last (low-ordered) field in any byte with unused space is moved to 
the low Ng of the byte. (This happens even if it's the only field in 
the byte. 


Unpacked Records 


Fields of unpacked records are packed in order, starting on word boundries, 
except for booleans and subranges that can fit in a byte. Values that don't 
take up a full byte or word will be packed at the low-ordered end of that 
space. 


The whole record will take up either one byte or an even number of bytes. 


For exemple, a record containing a subrange of 0..15, two integers, and a4 
boolean would be packed as follows: 


? BYTE 1 0? BYTE 2 o 7? BYTE 3 0? BYTE 4 9 
TTT} COT) pep 
2 BYTE 5 07 syte 6 6 9 BYTE 7 0? eve & 0 
[+———— integer 2———+] [TT TTT Tle] LITT 


| 
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Packed Arrays 


Packed arrays are also code-expensive, except for packed arrays of char. 
(These are treated as a special case, and the code associated with them is 
compact . ) 


The number of bits per element in a packed srray is the smallest of 1,2,4,8 or 
16 bits that will accommodate the element. For exemple, a subrange of column 
A requires the number of bits per element in column B: 


A 8B 
O..1 1 
0..2 2 
0. .3 2 
0. .4 4 
Q..10 4 
0..20 8 
0. .255 8 
0. .395 16 


Booleans sre packed one boolean per bit. The packed array as a whole must 
occupy an even number of bytes. 


R packed array[1..5] of boolean would be packed as follows: 


= BYTE 1 0 7? BYTE 2 0 
TT Tiss} CLL TTT 


A packed array[1..5] of [0..6] would be packed as follows: 


? eve 1 0 ? BYTE 2 0 ? BYTE 3 0 7 ByTE 4 0 
ee ee ls] 


You can use the 3 operator to poke around inside any packed value and thereby 
discover what the packing algorithm (probably) is. 


Signed Subranges 


Signed subranges (e.g. -5..14) are packed in packed types (unlike UCSD Pascal, 
which won't pack them). The minimum field size for a signed subrange is the 
minimum number of bits needed to represent any number of the subrange in two's 
complement form. 


The minimum field size is then subject to the rules for 4 particuler packed 
type. For example, though -1..2 only needs three bits, if it's in a packed 
array, it will take up four (see above table). If it's in a packed record, on 
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the other hand, it might take up only three bits, or it might use a whole 
byte, depending on what's packed around it. 


NOTE. 


A variable of type -127..128 takes up a dyte. 
A variable of type O..255 takes up a word. 
A variable of type char takes up 4 word. 
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PASLIB Procedure Interface 


(Workshop Release 1.0) 


PASLIB is the Pascal run-time support library. It provides the procedures and 
functions that ere built into the Pascal language, acts as the run-time interface to 
the Operating System, and “completes” the 68000 instruction set by providing routines 
for the compiler-generated code to call upon in lieu of actual hardware instructions. 


The interface to PASLIB is very tightly coupled with the Pascal compiler, and 
is very likely to be changed to improve performance and reduce code size. For 
this reason, only call these routines from assembly language if you absolutely 
and positively have to; stay in Pascal as much as possible when dealing with 
PASLIB. Most of these routines support the Pascal built-in procedures, which 
ere described ir detail in the Fasca/ Reference Nanual. 


There are & few conventions for using these routines, which must be followed 
to ensure correct results and successful execution. All the routines are 
called with parameters passed on the stack. The paremeters are pushed onta 
the stack in the order of the paremeter list shown in each routine. ‘ST.L' 
indicates a four-byte parameter, ‘ST.W' two-byte, ‘ST.B’ one-byte (stored in 
the upper byte of a word), and ‘ST.S' a set. The paremeters passed will be 
popped by these routines before return. The function results, if any, will be 
returned on the stack after the paremeters are popped out. Note that the 
function-type routines do not expect room for the function result to be 
reserved on the stack before the call. Also note that these routines do not 
check for room on the stack; the caller must guarantee enough room on the 
stack for saved registers. The caller should follow the Pascal procedure 
preamble code for expanding the stack before calling these routines. Standerd 
register preservation conventions are followed except in the routines 
indicated. Refer to the Alorkshop User's Guide for the usage of the special 
registers and the stack freme allocation. 


Contents 
1. Initialization and Termination Routines .......... 2 
2. Integer Arithmetic Routines .................0.0. 3 
3. Data Move and Scan Routines ..................-. 4 
4. String Manipulation Routines ................... 6 
5. String Comparison Routines .................... 6 
6. Set Manipulation Routines ..................... 8 
7. Miscellaneous Routines .....................5. 10 
8. Range Check Routines ..................... coed Gc 
SG. Heap Routines ................. detgtiedier it (oe lah Grados 12 
10. Read and Write Routines ....................2.. 15 
ai. “hie P/O ROUULNGS 2 cc 603 oe OMA we eee 22 
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1. Initialization and Termination Routines: % BEGIN, %_END, %_INIT, %_TERM 


None of these routines have paremeters, return values, or destroy any 
registers. 


Every main progrem must have the following beginning and ending sequences 
calling these routines: 


JSR % BEGIN ; beginning sequence 

LINK A6, #$0000 ; no-op for LisaBug, to look like standard module 
head 

MOVE.L  (A7)+, AG 

LINK AS, #$0000 ; set up global freme for main program 

SUBA.L $0010( 85), AR? ; variables for units, etc. passed by losder 

JSR %_INIT 


; main progrem code goes here 


JGR %_TERM ; ending sequence 

UNLK AS 

JGR %_END 

RTS 

UNLK A6 ; no-op for LiseBug, to look like standard module 
tail 

RTS 


Note that the size of the program global variables allocated to the loader 
is offset +16 from register AS. 


%_BEGIN - Beginning routine. Currently 6 no-op; reserved for future 
extensions. 


% END - Ending routine. Currently a no-op; reserved for future extensions. 


% INIT - Initializes PASLIB internal global data for each process: 


1. Sets up an f-line trap routine, which signals 4 “sys_terminate" 
exception if an f-line trap is encountered in the user code, 
terminating the program. 


2. Sets up global input and output file buffer addresses. These 
buffers are used for screen, keyboard, exec files and output 
redirection. The address locations ere fixed on the stack: the 
input buffer address is offset +8 from register A5; the output 
buffer address is offset +12. They are set up to point to global 
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file buffers in the shared data area of PASLIB. 
3. Initializes the OS exception handlers. 
4. Initializes the Pascal heap local variables. 


NOTE: The %_INIT routine will restart at step 5 if the calling process 
is a resident process. 


5. Initializes the PASLIB local variables. 
6. If the floating-point library IOSFPLIB is linked, it is 


initialized. 


% TERM — Terminate. If the process is resident, it jumps to step 5 of 
% INIT (see above), if not, it calls the OS routine "Hit_End" to 
terminate the process. Control does not return after this call. 


2. Integer Arithmetic Routines: 2]_M4, %I_DIV4, %I_MOD4 
%I_MUL4 - Multiply two 4-byte integers 


Paremeters: ST.L - Argument 1 
ST.L - Argument 2 


Returns: ST.L - Product 
Registers used: All registers sre preserved. 


The multiplication algorithm is as follows: 


-argument 1's upper word is multiplied by argument 2's lower word. 

-argument 2's upper word is multiplied by argument i's lower word. 

-these two products are added, and the sum is put in the result's 
upper word. 

-the two arguments’ lower words are multiplied, and this value is 
put in the result's lower word. 
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“I1_DIV4 - Divide two 4-byte integers 


Parameters: ST.L - Dividend 
- ST.L - Divisor 


Returns: ST.L - Quotient 

Registers used: All registers are preserved. 

The division is performed by subtracting the dividend from the 

divisor 31 times (for each of the 32 bits except the sign bit). 
%I_MOD4 - Remainder from the division of two 4-byte integers 


Parameters: ST.L - Dividend 
ST.L - Divisor 


Returns: ST.L - Remainder 
Registers used: All registers are preserved. 


The division is performed in the same way as %I_DIY4, above. 


3. Data Move and Scan Routines: %_MOVEL, %_MOVER, %_FILLC, %_SCANE, %_SCANN 
% MOVEL - Moveleft 


Perameters: ST.L -— From Address 
ST.L - To Address 
ST.W- Number of bytes to move 


Returns: —_— 

Registers used: DO, D1, D2, AO, Al, AZ 

If the number of bytes to move is 7 or less, they are moved a4 byte 
at atime. If the source address + 2 is the destination address, 
the data is moved one word at a time. If there are more than 7? 


bytes to be moved, then data is moved a long word at a time. If 
the ending address is a byte address, the trailing byte is moved. 
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% MOVER - Moveright 
Parameters: ST.L - From Address 
ST.L - To Address 
ST.W - Number of bytes to move 
Returns: -—- 
Registers used: DO, AD, Al, AZ 


Data is moved one byte at a time. 


“%FILLC - Fillchar 
Paremeters: ST.L - Address to fill 
ST.W - Number of bytes to fill 
ST.W - Fill character 
Returns: -——- 


Registers used: DO, Di, AD, A2 


Fills the address with the given character one byte at a time. 


%_SCANE - Scan equal 
Parameters: ST.W—- Length to scan 
ST.W - Character to scan for 
ST.L - Address to scan 


Returns: ST.W - The pea of the character (0 being the 
first 


Registers used: All registers are preserved. 
Scans the string for the given character, one byte at a time. 


Note that “Length to scan" can be negative, and the scan will go 
in the lower address direction. 
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%_SCANN - Scan not equal 
Parameters: ST.W- Length to scan 
ST.W - Character to scan for 
ST.L - Address to scan 
Returns: ST.W - The first character position that is not equal 
to the character to scan for (0 being the 
first) 
Registers used: All registers are preserved. 
Scans the string for the first character not equal to the given 
character, one byte at a time. 
Note that "Length to scan” can be negative, and the scan will go 
in the lower address direction. 
4. String Manipulation Routines: %_CAT, %_POS, %_COPY, %_DEL, %_INS 
All the string manipulation routines are performed one byte at a time. 
( 
%_CAT - Concatenate 
Parameters: ST.L - Address of ist string 
ST.L - Address of 2nd string 
STL - Address of Nth string 
ST.L - Address to put result 
ST.W-N 
Returns: oo 
Registers used: All registers are preserved. 
Copies all the given strings to the result string. 
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% POS - Position of one string in another 


Parameters: ST.L - Address of substring 
ST.L - Address of main string 


Returns: ST.W - Position 


Registers used: All registers are preserved. 


Compares the substring with the main string until a match is 


found. If no match is found, 0 is returned. 


% COPY - Copy a substring 
Paremeters: ST.L - Source string address 
ST.W - Starting index 
ST.W - Size to copy 
ST.L - Address of result 
Returns: — 


Registers used: All registers are preserved. 


If the number of bytes to copy is 0, or if the source string is 
longer than the number of bytes to copy, the result string has 0 


lenth. 


% DEL —- Delete & substring from a string 
Paremeters: ST.L - Address of string 
ST.W - Position to start deleting 
ST.W - Number bytes to delete 
Returns: --~ 


Registers used: DO, Dl, D2, D3, AO, Al, A2 


%_INS - Insert one string in another 
Parameters: ST.L - Address of string to insert 
ST.L - Address of main string 
ST.W - Position in main string to insert 
Returns: = 


Registers used: DO, Di, D2, D3, AD, Al, AZ 
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5. String Comparison Routines: %S_FQ, XS_NE, 3S_LE, 3S. GF, 2S_LT, %5_GT 
All the string comparison routines are performed one byte at a time. 


%3_EQ - String equal 

%_NE - String not equal 

%S_LE - String less than or equal 
4%>_GE - String greater than or equal 
%S_LT - String less than 

%5_GT - String greater than 


Paremeters: ST.L - Address of first string 
ST.L - Address of second string 


Returns: ST.B - Boolean result 


Registers used: All registers are preserved. 


6. Set Manipulation Routines: %_INTER, %.SING, %_UNION, %_DIFF, % RDIFF, | 
% RANGE, %_ADJ, % SETGE, % SETLE, % SETED, ( 
% SETNE : 


The format of a set an the stack is: 


. aaneneeenemname + high address 
|} i5-0 | 
whe ent 
| 31 - 16 | 
y eauuieietemamened —+ 
| | 
+--------- + 
jlast word! 
$——— +--+ 
| # Bytes | 


+--- —+ low address 
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%_INTER - Set intersection: seti AND set2 

%_UNION - Set union: seti OR set2 

% DIFF - Set difference: seti AND (NOT set2) 

%_RDIFF - Reverse set difference: (NOT seti) AND set2 


Perameters: ST.S - First set 
ST.S - Second set 


Returns: ST.S - Result set 


Registers used: All registers are preserved. 


%_SING - Singleton set 
Parameters: ST.W - Singleton value 
Returns: ST.S -— Result set 


Registers used: All registers are preserved. 


% RANGE - Set range 


Parameters: ST.W - Minimum value 
ST.W -— Maximum value 


Returns: ST.S - Result set 
Registers used: All registers are preserved. 
Returns the set representation of the values from minimum to 
maximum. If minimum is greater than maximum, a null set is 
returned. 

%_PDJ - Set adjust 


Peremeters: ST.S - Set 
ST.W - Desired size in bytes 


Returns: ST.S' - Adjusted set without size word 

Registers used: All registers sare preserved. 

Changes the size of a set to the given size. If the set is larger 
than the desired size, the extra values are thrown out; if the set 


is smaller than the desired size, extra fields are added and 
initialized to 0. 
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%_SETNE - Set inequality test 
% SETEQ - Set equality test 
% SETGE - Set inclusion test (returns true if set2 is the same as or 


included in seti) 


% SETLE - Set inclusion test (returns true if seti is the same as or 


included in set2) 


Paeremeters: ST.S -— First set 
ST.S - Second set 


Returns: ST.W - Boolean Result 


Registers used: All registers are preserved. 


7. Miscellaneous Routines: x_GOTOXY, %_GOTO, %_HALT 


%_GOTOXY 


% GOTO - 


- Move the cursor to a specified location 


Parameters: ST.W- X coordinate 
ST.W - Y coordinate 


Returns: --- 
Registers used: DO, Di, D2, D3, AD, Al, AZ 


%_GOTOXY sends the following escape sequence to the screen to move 
the cursor position: ESC 


Y+32 
X+32 


Y values are between 0 and 31; X values between 0 and 79. If the 
coordinate given is outside these bounds, it is set equal to the 
boundry value. 

Global GOTO code segnent remover 

Parameters: ST.L - Pointer to the desired last-segment jump table 
Returns: -—— 

Registers used: AO 


Jumps from a nested routine to the first-level process. 
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% HALT - Halt 


If the process is resident, it goes to step 5 of the %_INIT 
routine. If not, it calls "terminate_process" with the value of 
event_ptr as nil. Control does not return after this call. 


8. Range Check Routines: <_RCHCK, %_SROMK 
%_RCHCK -— Range check, to check the bounds of subrange type variables 


Parameters: ST.W- Value to check 
ST.W -— Lower bound 
ST.W - Upper bound 


Returns: -——— 
Registers used: All registers are preserved. 


Note that if the check fails, this routine causes the system 
exception ‘SYS _VALUE_00B' to be signalled and the message ‘VALUE 
RANGE ERROR' to be displayed before the process is forced to enter 
the debugger. If the process has not declared an exception 
handler for this exception, the system default handler is entered 
after the debugger returns control. The system default handler 
terminates the process. 


%_SRCMK - String range check, to check a string index against its length 


Parameters: ST.B —- Value to check: 0..255 
ST.W - Upper bound 


Returns: —— 
Registers used: All registers are preserved. 


Note that if the check fails, this routine causes the system 
exception ‘SYS_VALUE_00B' to be signalled and the message ‘ILLEGAL 
STRING INDEX' to be displayed before the process is forced to 
enter the debugger. If the process has not declared an exception 
handler for this exception, the system default handler is entered 
after the debugger returns control. The system default handler 
terminates the process. 
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9. Heap Routines: % NEW, %_MARK, %_RELSE, % MEMAV, %_HEAPRES 
% NEW - The New procedure. Allocate memory in the Pascal heap. 


Parameters: ST.L - Address of pointer 
ST.W - Number of bytes needed 


Returns: -—— 
Registers used: DO, Di, D2, D3, AD, Al, AZ 
% NEW sets the address of the pointer to nil. 


% NEW checks whether the heap has been initialized (whether a data 
segment has been allocated) via the boolean HeapInited. If 
HeapInited is false, a call is made to the GrowHeap function to 
create and initialize a ‘new heap’. If GrowHeap is unsuccessful 
(returns false} then % NEW is exited with the pointer set to nil. 


The GrowHeap function initializes a ‘new heap’ by calling the 
PLInitHeap procedure. Growheap passes PLInitHeap the size of 

the Pascal heap data segement, the memory size (HeapDelta) and 
the logical data segnent number (LDSN = 5). PLInitHeap then 
creates a private data segment with the pathname PascalLHeap, ( 
and assigns the segment pointer address to the pointers 
HeapStert and HeapPtr. PLInitHeap sets the pointer HeapEnd to 
NG to the end of the segment (HeapStart + segment size - 
236). 


Before assigning an address to the pointer, %_NEW determines 
whether there is enough room on the heap (i.e. in the data 
segnent) for the variable. %_NEW makes a second call to the 
GrowHeap function. If GrowHeap is unsuccessful, then %_NEW is 
exited with the pointer set to nil. 


The Growteap function calls the GetSafeAmmount procedure to 
determine the maximum number of bytes by which the heap can be 
increased (the amount of system memory available to the calling 
process). If this emount is greater than the current size of 
the heap, then GrowHeap will double the size of the heap, 
otherwise GrowHeap will increase the heap to the maximum emount 


available. The pointer HeapEnd is incremented by the emount of 
increase. 


%_NEW then sets the address of the pointer to the address of 
HeapPtr, which points to the next free area on the heap. The 
address of HeapPtr is increased by the size of the variable that 
was placed on the heap. 
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% MARK - The Mark procedure. Mark the Pascal heap. 


Paremeters: ST.L - Address of pointer to be marked 
ST.W - Number of bytes needed 


Returns: --- 

Registers used: DO, D1, D2, D3, AD, Al, A2 

%_MARK checks whether the heap has been initialized via the 

boolean HeapInited. If HeapInited is false, a call is made to the 

GrowHesp function to create and initialize a ‘new heap’. If the 

function is unsuccessful (returns false) then %_MARK is exited. 
The GrowHeap function is described under % NEW, above. 

% MARK sets the address of the pointer to the address of HeapPtr, 

which points to the next free ares on the heap. 

% RELSE - The Release procedure. Release the Pascal heap. 

Peremeters: ST.L -— Address of pointer to release to. 

Returns: --- 

Registers used: DO, D1, D2, D3, AD, Al, AZ 

%_RELSE checks whether the heap has been initialized via the 

boolean HeapInited. If HeapInited is false. as call is made toa the 

GrowHeap function to create and initialize a ‘new heap’. If 

GrowHeap is unsuccessful (returns false) then %_RELSE is exited. 
The GrowHeap function is described under % NEW, above. 

If the pointer does not point within the heap {i-.e., address 

memory between HeapStart and HeapEnd), an error will result and 

the procedure will be exited. 

If the pointer is less than HeapEnd minus HeapDelta, (where 

HeapDelts is the original size of the heap) the heap is reduced in 

size by HeapDelta. 


% RELSE sets HeapPtr (which points to the next free area on the 
heap} to the address of the pointer. 
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%_MEMAY - The Memavail function. Memory Available in the Pascal heap. 
Parameters: None. 
Returns: -—_— 


Registers used: All registers are preserved. 


%_MEMAY generates a call to the %_PrWordsAvail function, which 
determines the amount of words available. 


%_PHWordsAvail checks whether the heap has been initialized via 
the boolean HeapInited. If HeapInited is false a call is made to 
the GrovHeap function to create and initialize a ‘new heap’. If 
GrowHeap is unsuccessful (returns false) then % PHWordsfAvail is 
exited. 


The GrowHeap function is described under % NEW, above. 


% PHiordsAvail determines the maximum number of words available 
(the emount left in the heap data segnent minus the maximum amount 
of system memory available) and the current number of LDSN words 
evailable (the maximum number of words you can get by the chosen 
LDSN minus the number of words already used). If the maximum 
number of words available is greater than the current number of ( 
LDSN words available, then the current number of LDSN words 
available is returned, otherwise the maximum number of words 
available is returned. 


% HEAPRES - The HeapResult function. 
Peremeters: ST.W- Heap result 
Returns: -—- 


Registers used: All registers are preserved. 


Refer to the dorkshop User‘s Guide for the values of the heap 
result. 


%_HEAPRES generates a call to the %_HHeapRes function. %_HHeapRes 
is assigned the integer value of HErrResult. 
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10. Read and Write Routines: %_KEYPRESS, 2W_LN, 28_C, 28_STR, 28 PAOC, w_I, 


Rll the read and write routines take ‘file address’ as a parameter, which 
is the address of the file variable. The address of the Pascal standard 


input is in offset 8 from register AS; the address of output is in offset 
12 from AS. 


%_KEYPRESS - The Keypress function. 
Peremeters: ST.L - File address 
Returns: ST.B - Boolean Result 
Registers used: All registers are preserved. 


Note that the file address is not used in the current implements- 
tion. 


%_KEYPRESS generates a call to the %_PKeyPress function and 
returns the result of % PKeyPress as its result. 


The % PKeyPress function determines whether any keys have been 


pressed. It returns true if the look-ahead buffer is full, 
otherwise it returns false. 


“N_LN - WriteLn 
Parameters: ST.L - Address of output file 
Returns: = 
Registers used: DO, Di, DZ, D3, AD, Al, AZ 
“LN calls the FWriteln procedure, passing it the address of the 


file. FWriteln calls the FWriteChar procedure, passing it an 
ASCII <CR> (end-of-line) to be appended to the string. 
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“iC - WriteChar. Display a character on the console. 


Peremeters: ST.L - Address of output file 
ST.B - Character to be output 
ST.W- Size of field to print 


Returns: --- 
Registers used: DO, Di, D2, D3, AO, Al, AZ 


va_C calls the FWriteChar and OutCh procedures to write a 
character to the file. %W_C passes OutCh the character to be 
written and the address of the output file. OQutCh then calls 
FWriteChar to write the character to the file. 


The default field size is 1. If the field size is greater than 1, 
va_C calls FuwriteChar to write out the appropriate number of 
spaces, then calls OutCh, which calls FWriteChar to write the 
character. 


AI_STR - Write string 


Paremeters: ST.L - Address of output file 
ST.L - Address of string ( 
ST.W - Size of field to print 


Returns: --- 
Registers used: DO, Di, D2, D3, AO, Ai, A2 


If the string size is greater than 255 characters, then “_STR 
truncates it to 255. 


“@A_STR then compares the field size (MinWidth) to the specified 
string size. If the field size is less than or equal to zero, 
it's set to the string size. If the field size is less than the 
string size (but greater than zero), then the string size is set 
to the field size. If the field size is greater than the string 
Size, then a call is made to the FWriteChar procedure to write out 
{[MirWidth minus string size] spaces. 


“_STR then calls FWriteChar to write out the string with the 
specified string size. 
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7 _PAOC - Write a packed array of characters 
Parameters: ST.L -— Address of output file 
ST.L - Address of string 
ST.W - Actual length 
ST.W - Size of field to print 
Returns: -_- 
Registers used: DO, Di, D2, D3, AO, Al, A2 


The effect of 2_PAOC is the seme as calling “W_STR with the 
specifed field size equal to the number of elements in the array. 


WAi_I - Write an integer 
Paremeters: ST.L - Address of output file 
ST.L - Value to print 
ST.W - Size of field 
Returns: -_- 
Registers used: DO, Di, D2, D3, AO, Al, AZ 
4A_I compares the field size (MinWidth) to the size of the 
integer. If the field size is greater than the size of the 
integer, then “W_I calls the FWriteChar procedure to write out 
(MirWidth minus integer size] spaces. 


i_1 then calls FWriteChar to write out the integer with the 
specified integer size. 


2/—- J8NUETY 84 PRSLIG-17 


internals @ Contidentiai 


( 
“y_B - Write a boolean 
Parameters: ST.L - Address of output file 
ST.B - Yalue to print 
ST.W - Size of field 
Returns: _—- 
Registers used: DO, Dl, D2, D3, AD, Rl, AZ 
“#_B calls the “4_STR procedure, passing it the string to be 
written, the size of the string, and the address of the output 
file. 


If ‘value to print’ is zero, %4_B passes the string ‘FALSE’ to 
AN_STR, with a string size of 5. 


If ‘value to print’ is 1, 4)_B passes the string ‘TRUE’ to W_STR, 
with a string size of 4. 


@a_STR then writes the string to the output file. 


%_PAGE - Page procedure 
Peremeters: ST.L -— Address of output file 
Returns: | --- 
Registers used: DO, Di, Dz, D3, AD, Al, A2 
%_PAGE writes the ASCII character ‘FF’ to the output file by 


calling the OutChar procedure. OutChar is passed the character to 
be written (e.9. 'FF') and the address of the output file. 
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Y_C - ReadChar 
Parameters: ST.L - File Address 
Returns: ST.B - the character read 
Registers used: DO, D1, D2, D3, AO, Al, AZ 


“RC reads a character from the specified file by calling the InCh 
function, then returns the character on the stack. 


InCh calls the FReadChar function, passing it the file address. 
FReadChar verifies that the file has been opened, calls the 
FGet procedure, reads the character that is placed in the 
window buffer area by FGet, and passes the character back toa 
Inch. 
2R_LN - ReadLn 

Paremeters: ST.L - Address of input file 

Returns: -—- 

Registers used: DO, Di, D2, D3, AO, Al, AZ 


“R_LN reads a line from the specified file by calling the FReadLn 
procedure, passing it the file address. 


FReadLn verifies that the file has been opened and then calls 
the FGet procdure to read each character on the line until EOLN 
is true. When EOLN is true, FReadin resets EOLN to false and 
returns to 2R_LN. 
4R_PAOC - Read Packed Array of Character 
Parameters: ST.L - File Address 
ST.L - Array Address 
ST.W - Size of array in bytes 
Returns: — 
Registers used: DO, Di, D2, D3, AD, Al, AZ 


The effect is the seme as calling “R_STR whose specified field is 
the number of elements in the array. 
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4_STR - Read String 


Parameters: ST.L - File Address 
ST.L - String Address 
ST.W - Max size of string 


Returns: _—— 
Registers used: DO, Di, D2, D3, AD, Al, AZ 


@_STR first verifies that EOLN is false, otherwise “R_STR returns 
to the calling routine. 


ZR_STR then generates a loop which reads a character from the file 
by calling the InCh procedure (described under *_C, above), then 
checks whether EOLN is true. If EOLN is true, “*R_STR returns to 
the calling routine. If EOLN is false, “<R_STR reads the character 
and returns to the beginning of the loop to read the next 
character . 


After InCh returns a character, “R_STR checks whether the 
character is a RUBOUT (ASCII 'DLE') or BACKSPACE (ASCII 'BS'). If 
the cheracter is either of the two, “R_STR processes the character 
accordingly and then reads the next character. If the character ( 
is not RUBOUT or BACKSPACE, the character is read and #_STR 
returns to the beginning of the loop to read the next character. 


AR_I - Read Integer 
Peremeters: ST.L - File Address 
Returns: ST.B - The integer read 
Registers used: DO, Di, D2, D3, AO, Al, A2 


%W_I consists of two main loops which reads characters from the 
file to form a4 valid representation of an integer value. 


The first loop reads a character from the file by calling the InCh 
procedure (described under %R_C, above). If this character is 
<CR> or space, *_I returns to the beginning of the loop to read 
the next character. If the character is not <CR> or space, “*_I 
exits the first loop. 


Next, 2R_I determines whether the character read is a sign 


character ('+' or ‘-'). If it is, *&R_I enters the second loop and 
calls InCh to read the next character. If the character is not a 


: 
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Sign character, “R_I enters the second loop bypassing the call to 
InCh. 


The character is then checked to see if it's a RUBOUT or BACKSPACE 
character; if it is, the character is processed accordingly and 
W_I returns to the beginning of the first loop. 


The character is checked once more to determine if it is a valid 
integer value (0 « character < 9). If it is, ®_I returns to the 
beginning of the second loop and calls InCh to read the next 
character . 


If the character is not a valid integer, then “*R_I checks to see 
if any characters read previously have been valid integers (by 
checking register D6). If no characters have been valid integers 
(D6 = 0), then *&_I generates an I0Result error. If the characters 
read previously have been valid integers (D6 =1), then *#_I 
returns to the calling routine with an integer result. 


End of line predicate 
Parameters: ST.L - File address 
Returns: ST.B - Boolean Result 


Registers used: All registers are preserved. 


% EOLN returns true if the end of a line has been reached in the 


specified file. 
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11. File 1/0 Routines: %_REWRT, %_RESET, *<_CLOSE, %_EDF, %_BLKRD, %_BLKRR, 


% IORES, % GET, % PUT, % UPARR, % SEEK 


%_REWRT - Rewrite a file 


Parameters: ST.L - File Address 
ST.L - Address of Neme String 
ST.W - Kind: -2=text, -l=file, >O=number of words per 
record 


Returns: -——— 
Registers used: DO, Di, Dz, D3, AD, Al, AZ 
Creates and opens a new file. 


% REWRT first initializes the file's FIB (file identification 
block} by making a call to FInit and passing it the file type via 
the parameter recBytes. Once the file type is determined, the 
value of FRecSize is initialized. The values of recBytes and 
FRecSize and the file types are: 


recBytes file type FRecSize 
-2 text -1 
-1 untyped 0 ( 
0 interactive -1 
6) typed value in recBytes 


Other important FIB entries are initislized as follows: 


FIsOpen false .. The file is merked as not open 

FNewFile false .. The file is merked as not new 
(i.e. no creation of new files) 

true .. End Of File is set to true 

true .. End Of Line is set to true 

. The file is marked as not modified 

true .. The file is marked as an OS File 


FEOF 

FEOLN : 
FModified: 
FIsOS : 


it ues il 
gz 
a 


% REWRT then calls FOpen. Within FOpen: 


A check is made to determine whether the file has been opened 
by referencing the boolean FIsOpen. If FIsOpen is true, an 
IOResult error will occur; if not, it is set to true. 


FOpen then determines whether the filename is one of the 
character devices CONSOLE, KEYBOARD, or PRINTER. If it is, 
FOpen opens the file. If the filename is PRINTER, a4 check is 
made to determine if the printer is connected. If the printer 
is not connected. an JOResult error will be generated. The FIB 


( 
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veriable FUnit is also set accordingly: 1=CONSOLE, Z2=KEYBOARD, 
3=PRINTER, 10=other devices (not pseudo devices). 


The FIB variable FNewFile is set to true to indicate that a new 
file is being created with a rewrite, otherwise its value would 
remain false indicating a reset operation. 


FOpen creates and opens a new temporary file if the filename 
does not exist (i.e. if FNewFile is true), otherwise it opens 
the existing file. If the temporary file is of type TEXT, 

FOpen writes two header blocks of null to the file. FOpen also 
kills the temporary file so that it may be unkilled during the 
close. 


%_RESET - Reset a file 


Parameters: ST.L - File Address 
ST.L -— Address of Name String oS 
ST.W - Kind: —2=text, -l=file, >O=number of words per 
record 


Returns: -—- 

Registers used: DO, Di, D2, D3, AO, Al, AZ 

Opens an existing File. 

% RESET behaves in the same manner as %_REWRT, by making calls to 
procedures FInit and FOpen. However, %_RESET does not create a4 
temporary file (FNewFile is false). It attempts to open the 


existing file and if it is unsuccessful will issue an IOResult 
error. 


Before exiting FOpen, % RESET makes a call to the FReset procedure 


which in turn calls the FGet procedure. This has the effect of 
advancing the file position to the first record of the file. 
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% CLOSE - Close a file 


Paeremeters: ST.L - File Address 
ST.W - Mode: O=NORMAL, 1=LOCK, 2=PURGE, 3=CRUNCH 


Returns: --- 
Registers.used: DO, Di, D2, D3, AD, Al, A2 


If the file is a character device (e.g. console, keyboard) or if 
the file is not open (FIsOpen is false), the close procedure has 
no effect. 


CRUNCH and LOCK Options: 


If the close option is either CRUNCH or LOCK, and the file is a 
text file that had been opened by RESET (FNewFile is false), a 

check will be made to determine if the number of blocks is odd. 
If it is, @ null block will be written to the end of the file. — 


If & previously existing file was opened by REWRITE (FNewFile 
is true), it will be killed (i.e. deleted}. Its temporary 

file, which was killed by FOpen, is unkilled using the original 
file name as the new file name. | 
PURGE Option: : 


If the file was created by REWRITE, the temporary file will 
have already been killed in FOpen. 


The PURGE option will kill the original file provided it was 
opened by RESET (FNewFile is false). 


NORMAL Option: 


If the file was created by REWRITE, the temporary file will 
have already been killed in FOpen. 


The original file is left untouched. 
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%_EOF - End of file predicate 
Parameters: ST.L -— File address 
Returns: ST.B - Boolean Result 
Registers used: All registers ere preserved. 
Detects the end of ao file by referencing the FIB boolean entry, 
FEOF . 
%_BLKRD - Blockread 
Perameters: ST.L - File Address 
ST.L - Buffer address 
ST.W - Number of blocks to read 
ST.W - Block Number, -1 = Sequential 
*eeeee 6 OST W - DoRead, O = write, 1 = read eset 
Returns: ST.W - Number of blocks actually read 
Registers used: DO, D1, D2, D3, AD, Al, AZ 
%_BLKRD generates a call to the FBlockIO function, passing the 
parameters listed above. The boolean variable DoRead is set to 
true for Blockread and false for Blockwrite. 
Within FBlockI0: 
If the file is not open (FIsOpen=false) and the number of 
blocks to transfer is less than zero, FBlockIO will generate ar 
IOResult error and the file will not be processed. 
If the file is the character device CONSOLE or KEYBOARD, an 
IOResult error will be generated and the file will not be 
processed. = 


If the file is the character device PRINTER, the block number 
to start the transfer (RBLOCK) is set to -1. 


If the boolean DoRead is true, FBlockIO reads blocks from the 
file via a READ_DATA call, otherwise FBlockIO writes blocks to 
the file via a WRITE_DATA call. 


Before these OS calls can be made, the mode and offset must be 
determined. 
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If the block number to start the transfer (RBLOCK) is less than 


zero, the mode is SEQUENTIAL and the offset is zero, otherwise 
the mode is ABSOLUTE and the offset is calculated as: 


ord4(rblock) * FBlkSize 
where FBlkSize is the Standard Disk Block Length (512) 
The number of blocks actually read or transferred is calculated 
as: 

FBlockIO := actual div FB1kSize 
where ‘actual’ is the number of bytes transferred by the 
READ_DATA or WRITE_DATA OS calls. 


EOF (FEOF) is set to true when the last block is read. 


% BLKWR - Blockwrite 


Parameters: ST.L - File Address 
ST.L - Buffer address 
ST.W - Number of blocks to write 
ST.W - Block Number, -1 = Sequential 
**e44% = €©6ST.W - DoRead, O = write, 1 = read +Fe3* 


Returns: ST.W - Number of Blocks actually written 
% BLKWR behaves in the same manner as %_BLKRD, except it passes 
the boolean variable DoRead with a value of false when calling 
FBlockIO. 

%_IORES - [OResult 

| Perameters: None 
Returns: ST.W - IOResult 
Registers used: All registers are preserved. 
Refer to the #orkshop User's Guige for the values of IOResult. 
Returns an integer value that reflects the status of the last 
completed I/0 operation. Note that the code 0 indicates 


successful completions, positive codes indicate errors, and 
negative codes are warnings. 
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% IORES makes & call to function FIOResult, which in turns 
references the variable IORslt. The variable IORslt is assigned 
values by the procedure % SETIORSLT. This procedure is called by 
FPLib and appastext only. 

%_GET - Read the next record in a file 
Parameters: ST.L - File Address 
Returns: = 


Registers used: DO, Di, DZ, D3, A, Al, A2 


%_PUT - Write the current record in a file 
Peremeters: ST.L - File Address 
Returns: -—- 
Registers used: DO, Di, Dz, D3, AD, Al, AZ 
If % PUT is called immediately after a file is opened with 
%_ RESET, the PUT will write the second record of the file (since 
the % RESET sets the current position to the first record and 
%_PUT advances the position before writing). 
%_UPARR - Compute the address of F* 
Paremeters: ST.L - Address of file 


Returns: ST.L - Address of F* 


Registers used: All registers are preserved. 
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%_ SEEK - Allows access to an arbitrary record in a4 file. 


Parameters: ST.L - Address of file 
ST.W - Record number to seek 


Returns: -— 
Registers used: DO, Di, D2, D3, AOD, Al, A2 
If the record number specified does not exists, 


1) % SEEK causes the next GET to access the last record in the 
last block of the file. 


2) % SEEK causes the next PUT to append the record to the end 
of the file. 
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PaslibCall Unit 


(fron the workshop User's Guide ) 


The unit PASLIBCALL provides you with several system functions. In order to access 
the PASLIBCALL routines, you must use the units SYSCALL and PASLIBCALL: 


USES 
{$U SysCall} SYSCALL, 
{$U PaslibCall} PASLIBCALL; 


This gives you access to the routines listed below. These routines are contained in 
IOSPASLIB.OBJ, so programs using them require no additional inputs to the Linker. 


function PAabortFlag -: boolean 


This function tells whether or not the @-period key combination has been pressed. 
It enables programs to exit cut of long operations. The flag is cleared when 
PAbortFlag is called. If you want your program to stop when you press @-period, 
you must use this function in the prograrn ta detect that the key combination has 
been pressed. For example: 


{This program fragnent hangs in an infinite loop until @-period is pressed} 


aborted -=false 

Repeat {Wait for @-period. You might want to do other things here) 
aborted -:=PAbortFlag; 

until aborted. 


procedure ScreenCtr (contrfun : integer ); 


This procedure provides standard screen control functions, and enables programs ta 
perform screen control without having to to use escape sequences. (Escape 
sequences sre explained in Appendix C of the torkshap User's Guide) The 
pararneter specifies the screen control function. It is defined in the constants as 
follows, in the PASLIBCALL unit: 


Value 
Function Constant Decimal Hex 
cleer screeri CclearScreen 1 1 
clear to the end of screen CclearEScreen Z 2 
cleer to end of line CclearELine 3 3 
move cursor to horne position CgoHome 11 B 
cursor left one position Cleft Arrow 12 C 
cursor right one position CrightArrow 13 D 
cursor up one line position CupArrow 14 E 
cursor down one line position CdownArrow 15 F 
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Screen control example: 


{This program fragnent clears the screen, and positions the cursor on the 
third line} 

ScreerCtr (CgoHome); 

ScreerCtr (CclearScreen); 

ScreerCtr (Cdownfrrow); 

ScreerCtr (CdownArrow}); 


procedure GetGPrefix (var prefix : pathnene); 


This procedure provides your program with the first level prefix setting in the 
File-Mor in the Workshop. 


procedure GetPrDevice (var PrDevice : e_neme); 


This procedure returns the corresponding default printer device narne so that you 
can perform additional device control functions using DEVICE _CONTROL. (The 
Qperating Systern Reference Manual explains the device control] call.) The default 
printer device name is the one corresponding to the logical device -PRINTER. 
Note that the device name returned contains a leading '-’. 


procedure PLINITHEAP (var errnum, refnum-intecer; ( 
size, delta: longint : = 
ldsn- integer; 
swappable: boolean); 


eirnum = is the error number returned if the procedure has ary problerns 
making a data segment having a mem_size of size bytes. (See 
Appendix A of the tvorkshop Liser’s Guide for an explanation of the 


error codes.) 
size is the number of bytes in the heap. 
refrum iis the refrnurn of the heap. 
delta is the amount you want the data segment to increase when the 


current space is used up. If you use a lerge heap, use a large 
number for delta. 


ldsn is the logical data segment number used for the heap. The default is 
3S. For more information see the Qoerating System Reference Marusi 
for the Lise. 


swappable is the boolean that determines if the systern can swap the heap data 
segment out to disk if it needs to. 


This procedure can be used when you have special needs; for example, when you 
want to specify your own Idsn or heap size. When you use PLINITHEAP. you 
( 
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must call it before calling other heap routines. For more information on the heap, 
see the tvorkshog Lher’s Guide. 
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PPaslibC Unit: 
Privileged PASLIB Calls: 


The unit PPaslibC provides you with several useful low-level system functions. 
However, they are not for everyone! They are tricky, in some cases have global 
effects on the entire system, and should be used with caution. 


In order to use these routines, you must use the units SYSCALL and PPaslibC: 


USES 
{$U SysCall} SYSCALL, 
{GU PPaslibC} PASLIBCALL; 


This gives you access to the routines listed below. These routines are contained in 
IOSPASLIB.OBJ, so programs using them require no additional inputs to the Linker. 


procedure BlockIOinit; 


Initializes all shared PASLIB data. Opens inputfile and outputfile, 
associating them with the filename —CONSDLE. . . . 


BlockIOinit must be called by every shell before performing any 17; it 
will only be executed by the first shell that calls it. 


It is called by the system.shell at boot time, once for the entire suseeihy 


procedure BlockIOdisinit; 


PASLIB cleanup. BlockIOdisinit closes the console only for the first shell 
that called the BlockIOinit procedure. 


procedure LockPaslib (var errnum: integer); 
where: 


errmm is the error number returned if the procedure has any problems. 
(See Appendix A of the Workshop User's Guide for an — 
explanation of the error codes.) 


Locks the PASLIB1 segment in memory so it won't be swapped out. Used by 
the filer for unmounting the boot device. 


procedure LockPasIOlib (var errnum: integer); 
where: 
errmm is the error number returned if the procedure has any problems. 


Locks the PASIOLIB segment in memory so it won't be swapped out. Used by 
the filer for unmounting the boot device. 
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procedure MoveConsole (var errnum: integer; applconsole: consoledest); 

where: . : , es ee 
errnua’ is the error number returned if the procedure has any problems. _ 
applconsole tells where to move the console. (Consoledest is an — 


enumerated type of: alscreen, mainscreen, xsorocA, xsorocB, 
folder, sparei, spare2, spare3.) 


Moves the console to the main screen, an alternate screen, or an external 
terminal connected through RS232A or RS232B. The file names are: 


Alternate Screen —ALTCONSOLE-X 

Main Screen —MAINCONSDOLE—X 
~ External R3232R Terminal RS232A-X 

External RS232B Terminal RS232B-X 


procedure ExecReset (var errnum: integer; execfile: pathname; stopexec: 
_ boolean); 


where: : 
errnua : is the error number returned if the procedure has any problems. 
execfile is the exec file name. 


stopexec tells whether to open or stop the exec file. ( 
TRUE = stop; FALSE = open. 


If stopexec is TRUE, ExecReset closes the input file and 
reopens it, associating it with the temporary exec file. It 
then generates two calls to the FReadchar function to read and 
save the temporary file's first character into the variable 
ofirstchar, and the next character into greadahead. ExecReset 
then sets the boolean gexecflag to TRUE. 


If stopexec is FALSE, ExecReset calls the Resetinput procedure, 
which closes and reopens the input file, associating it with 
—-CONSOLE. ExecReset then sets the boolean gexecflag to FALSE. 


Opens or stops an exec file. 


ExecReset is called once by the Exec Command Interpreter, to open and read 
from the exec temporary file and reopen the input file to the console. 


function ExecFlag: boolean; . 
Tells whether an exec file is open. TRUE = open, FALSE = closed. 
ExecFlag references the input file FIB boolean entry FSOFTBUF. 
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procedure parece (var exrrnum: integer; outfile: pathname; stopoutput - 
boolean); 


where: 
errmua is the error number returned if the procedure has any problems. 
outfile is the file name. 


stopoutput tells whether to close the file or leave it open. 
TRUE = close; FALSE = leave open. 


If stopoutput is TRUE, OutputRedirect calls the Resetoutput 
procedure, which closes and reopens the output file, 
associating it with —CONSOLE. 


If stopoutput is FALSE. OutputRedirect closes the output file 
and reopens it. associating it with the filename outfile. 


Redirects output to a file. 


function OutputRFlag: boolean; 


Tells whether output has been redirected to a file. TRUE = output file 
open (output redirected); FALSE = closed (output not redirected). 


OutputRFlag references the output file FIB boolean entry FSOFTBUF. 


procedure DSPaslibCall (var ProcParem: dsProcParan); 
where: 


dsProcParam = record 
case ProcCode - dsProcCode of 
dsResProg : (RProcessId : longint); {must be called 
before the process starts rumning.} 
dsSoftPwhtn -: (SPButton : boolean); {result} 
dsPrintDev : (PrDevice : e_name); 
dsSetGPrefix - (errmum -: INTEGER; {result} 
prefix : pathname); 
dsEnbDisk : (DiskEvent : boolean); 
dsCilranLiseCer : (toTranslate - boolean); 
{to turn on or off translation for C. Itoh} 


F 


dsProcCode = (dsResProg, dsSoftPwhtn, dsPrintDev, dsSetGPrefix, 
dsEnkDisk, dsCiTranLisaCar); 


dsResProg passes the process ID of a@ process that is going to be 
resident to PASLIB. 


dsSoftPwhtn returns the soft power button setting. If the button is 
pressed, it returns TRUE; if not, it returns FALSE. 
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dsPrintdev passes the physical device neme of the corresponding 
logical device -PRINTER to PASLIB. 
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tells PASLIB to enable, (Gf DiskEvent is ey fiséble. 
(if DiskEvent is FALSE] the automatic mounting and “ 
ejecting of a diskette. 


dsCotranLisaCar tells PASLIB to turn on (if toTranslate is TRUE) or off 
(if tofranslate is FALSE) the Lisa character translation 


for aC. Itoh printer for the calling process. The 
default setting is on. 


DSPaslibCall is a new call in the PPaslibC unit that comnunicates to and 
from PASLIB about the run-time support for the system or the calling 
process. It has a variant-record parameter for indicating various 

- functions. Note that most of these functions dictate system behavior, they 


are not safe for any process to call except the Lisa character translation 
function. 
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Floating-Point 
Libraries 


Introduction 


The Lisa provides arithrnetic, elernentary functions, and higher level mathematical 
algorithms in its intrinsic units FPLib and MathLib, which ere contained in the file 
IOSFPLIB. 


The conterts of FPLib sre described in the manuals for the Standard Apple Numeric 
Environment. The best currently available description of the standard Apple Nurneric: 
Environment is the Awmerics Manual: A Guide to Using the Rople ws Fascal SANE 
and Elems Linits (part #030-0660-A), which will eventually be uiperteded by & 
manual applicable to all Apple products. FPLib provides the sarne functionality as 
the SANE and Elems units on the Apple ][ and ///, including: 


« Arithmetic for all floating-point and Comp types. 

= Conversions between numerical types. 

»« Conversions between numerical types, ASCII strings, and intermediate forms. 
« Control of rounding modes and numerical exception handling. 

» Common elementary functiaoris. 


The MathLib guide (currently in dreft form) describes the extra procedures available 
only on the Lisa. MathLib provides: 


« Extra environments procedures. 

e Extra elementary functioris. 

« Miscellaneous utility procedures. 

* Sorting. 

« Free format conversion to ASCII. 

= Correctly rounded corversion between binary and decimal. 
« Financial analysis. 

» Zeros of functions. 

=» Linear algebra. 


How to Use FPLib 


FPLib is available as an intrinsic unit to Pascal programmers. If your only use of 
floating point is as Pascal REAL variables used within the limits of standard Pascal, 
then it is not necessary to include a USES statement for FPLib. But if you explicitly 
require any of the types or procedures defined in the FPLib interface, be sure to 
include a USES statement such as 


USES FPLib; 


after the program statement in a main program or after the interface statemerit in a 
unit. If you ere also using other units, include FPLib in the list of units in your one 
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USES statement. FPLib may be listed before or after other Apple-supplied units that ( 
you are using. 


When linking, be sure to include JOSFPLIB in your list of files to be linked along wiht 
ISPASLIB and your own files, ever if your only use of floating point is as Pascal 
REAL variables. 


How to Use MathLib 


MathLib is available as an intrinsic unit to Pascal prograrnmers. When writing your 
Pascal source code, be sure to include a USES statement such as 


USES FPLib, MathLib; 


after the prograrn statement in a main program or after the interface statement in a 
unit. If you are also using other units, include FPLib and MathLib in the list of units 
in your one USES statement. They may be listed before or after other Apple-supplied 
units that you are using, but FPLib muct appear in the list before MathLib. 


When linking, be sure to include JOSFPLIB in your list of files to be linked along wiht 
ISPASLIB and your own files. 


( 
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TO: Developnent System Group, Mark Neubieser, Lee Nolan, Steve Flournoy, 
Wendell Henry 


FROM: Fred Forsnan 
DATE: March 31, 1983 
SUBJECT: Intrinsic unit providing standard functions -- the "StdUnit” 


Ssessrss2tenssssesssssssesessssss INTRODUCTION SSSSessessttstsssrss2trrsss2222rse2r===z2 


An intrinsic unit has been developed which provides a number of standard, 
generally-useful functions (particularly for the development system). The 
“StdUnit” unit has groups of functions dealing with (1) character and string 
manipulation, (2) file name manipulation, (3) prompting, (4) retrieval of error 
messages from disk files, (5) special WorkShop-oriented features, and (6) 
conversions. 


The StdUnit is now available in the WorkShop A5 intrinsic library. A 
non-intrinsic Monitor-based version of the unit is available in ny office. 


Development system tools should be converted to use the unit where possible, 
especially in the area of prompting and OS error reporting since this will help 
make the WorkShop interface more consistent. 


The rest of this memo explains the standard unit and its use. The material is 
organized into three sections: 


(1) FUNCTIONAL AREAS -- a description of the areas of functionality 
(2) SOME EXAMPLES -- some examples of how to use the functions 
(3) THE INTERFACE -- the unit's interface 


The five basic areas of functionality provided are: 
(0) Initialization of unit 


This is not really an area of functionality but it should not be overlooked. 
The unit needs to be initialized before it can be used. (Using the unit 
without initializing it will often result in an address or bus error. ) 


(1) String and character manipulation 


The unit provides a standard string type “SUStr", a type for sets of 
characters, definitions for a number of standard characters (such as CR 
and BS), and procedures for case conversion on characters and strings, 
trimming blanks, and appending strings and characters. 


NOTE: The names of EVERYTHING in StdUnit begin with the letters “SU”. 

This may seen somewhat unnatural, but it practically insures that you will 
have no name conflicts when incorporating the standard unit into your code. 
It has the additional benefit of identifying where everything cones fron. 


(2) File nane manipulation 


fi nunber of functions dealing with file names are provided -- determining 

if a pathnane is a volume or device name only, adding extensions (such as 

“. text”) to file names (the procedure is cognizant of our various 

conventions about when extensions should and should not be added), splitting 
a pathname into its three basic components (the device or volume component, 
the file name component, and the extension component), putting the components 
back together into a file name, and modifying a file name given optional 
defaults for missing volume, file or extension conponents. 


NOTE: several of the procedures return overflow flags for identifying when a 
file name component has exceeded its character limit. You may chose to 
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ignore the overflow condition, partic. -xly you think it likely to occur only 
in perverse circunstances. 


NOTE: you will notice that the string parameters to these procedures are 
often typed differently, sometimes SUStr’s, or VAR SUStr's, or SUStrP's 

(ie, pointers to SUStr’s). The apparent inconsistency of types is deliberate; 
the goal was to avoid awkward problems with Pascal string typing when using 
the procedures with strings which are not SUStr’s (PathNane’s for exanple). 

It might have been best to use only SUStrP’s, but the compiler does not 

allow @ of a string constant, so this would have been inappropriate when 
passing defaults such as ‘.text'. Plecse let me know if you can think of a 
way to make these procedures easier to use. 


Prompting 


The unit provides a number of procedures which get characters, strings, file 
names, integers, yes/no responses, etc. from the console, providing for 
default values where appropriate. An attempt was made to do a cosmetically 
nice job of echoing responses, displaying defaults, etc. (I am open to 
further suggestions. ) 


Most of the prompting procedures return a PromptState which indicate such 
things as whether an escape (CLEAR) was typed, whether the default was 
taken, or whether there was a request for options with a ‘?'. The states 
returned are given for each procedure. The strings and pronpt states 
returned have been designed to allow you to ignore the prompt states you 
are not interested in. For example, if you are not interested in treating 
‘?' as a request for options, you may ignore the SUOptions state altogether 
and treat the ‘7?’ returned as a file name or whatever. 


Error Text Retrieval 


The unit provides a mechanism which retrieves single-line error messages 
fron specially formatted error files. Error messages can be looked up by 
number in one or more error files. 

The original motivation for this was the aggravation of constantly looking 
up OS error numbers. Al error file for OS errors is provided in the WorkShop 
release -- ‘OSErrs.Err’. This makes it simple to return a real message when 
an OS error occurs, as is denonstrated in one of the examples in the 
following section. (Note that OS errors are also returned via Pascal's 
IORESULT. ) 


Whether the tool is useful for storing your progran's error messages will 
depend primarily on whether you think your error messages are taking up too 
much space in menory. fA program (described below) is available to make your 
own message files. One benefit of using this error mechanism is that you 
may add and modify messages without recompiling your progran. 


The "ErrTool" progran is provided to construct your own compacted error 
message files. The tool produces an error file with an ordered directory of 
error numbers at the beginning of the file, along with pointers to the 
corresponding message text. The input to ErrTool consists of text lines of 
the forn: 

<nunber ><space><message> 
The error numbers may be sparse, and the messages may be up to 255 chars 
long. 


Ai cail to retrieve a message will open the error file, search the directory 
for the error number, seek to the location of the message, and return the 
text. This may result in several file system accesses but the response seens 
reasonable (even with a large number of errors with a directory spanning 
several blocks as in the OS error message file). 


A program may use the unit to access any number of different error files 
simu:itaneously. You may, for example, access different files for OS and 
your own error messages. 
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(5) WorkShop Support 


Special WorkShop-oriented functions surr<-ted are: the ability to stop the 
execution of an EXEC file in progress, the ability to find out the nane of 
the boot and current process volumes (SysVols), and a super-RESET which will 
try to open a file first on the prefix volune, then on the boot volume, and, 
if all else fails, on the current process volune. 


(6) Conversions 


Routines to convert from INTEGERs (and LCNGINTIs) to strings and fron 
strings to INTEGERs (and LONGINTs) are provided. 


IMPORTANT NOTE: The standard unit and its interface have been written so as to 
work on either the Monitor or the OS depending on the setting of a compilation 
flag “For0S" which you should set before you use the unit (you will get a compile 
error if you don't). Note that the Monitor version of the interface provides a 
definition of “PathNane” which would normally come from SysCall when on the OS. 


{ EXAMPLE } 
Assume we are going to prompt for an output file name (OutFName) and that we 
already have the input file name (InFName). We will use SUSplitFN to split 
the input file name into its various components. Then we will pronpt for the 
output file name (with SUGetFN) using the volume and file name components of the 
input file name as defaults but with a °.ERR' extension. We then do a CASE on 
the prompt state (PState) returned by SUGetFN. Our progran will terminate if the 
file specification was an escape (CLEAR on the keyboard); say that no options 
are avaiicble if ‘7?’ is typed as an option request; prompt again if no file is 
specified, since we want to require an output file; and fall through if the 
default is accepted or some other file is specified. Note that we only have to 
check for the prompt states we are interested in for special handling. } 


9999: 
WRITE (‘Name of Error Output File ‘); 
SUSpiitFN (a@InFNane, @VolN, aFN, aExt); 
SUGetFN (a@0utFName, PState, VolN, FN, °.ERR’); 
CASE PState OF | 
SUEscape: EXIT (ErrFileP); { exit from program } 
SUOptions: BEGIN 
WRITELN (‘No options available. ‘); 


GOTO 9999; 
END; 
SUNone: GOTO 9999; 
END {CASE}; 
{ EXAMPLE 2 


Suppose we have just made a Pascal I0 call and want to report an error (along 
with the OS message text) if we receive a non-zero IORESULT. Note that we copy 
IORESULT into our JOStatus variable so that the subsequent WRITELN will not 
reset oe of IORESULT before we get a chance to use it. (EMsg should be 
an SUStr. 


IF IORESULT <> 0 THEN 
BEGIN 
JOStatus := IORESULT; 
WRITELN (‘Error openning input file. ‘); 
SUErrText (‘OsErrs.Err’, I0Status, @EMsg); 
WRITELN (EMsg); 


@ 


no 22+ -- 2-7-2222 2-2-2222 ---------- SU: StdUnit ---------------------------------- } 
Copyright 1983, Apple Computer, Inc. } 
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} 
This unit provides a nunber of standard type definitions and a collection of } 
procedures which perform a variety of common functions. The areas covered are: } 
(1) String and Character manipulation } 
(2) File Name Manipulation j 
(3) Pronpting 
(4) Retrieval of messages from disk } 
(5) Development System Support 
(6) Conversions 


Fred Forsman 3-28-83 
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INTERFACE 
{SIFC For0S} 
USES 
SU SysCall. obj SysCall, { for definition of PathName, etc. } 
SU PasLibCall.obj } PasLibCall, 
SU PPasLibC. obj PPasLibC; 
{SENDC} 
CONST 
SUMaxStrLeng = 255 
SUNUL1Str ae 
SUSpace a: 
SU0rdCR = 13; 
{SIFC For0S} 
SUMaxPNLeng = 66; max length of path nane } 
SUMaxVNLeng = 33; max length of volume name, includes leading ‘-' } 
SUMaxFNLeng = 32; maximun length of file name } 
SUVolSuffix = ‘-'; suffix or end of device cr volume nane } 
{SELSEC} 
SUMaxPNLeng = 39; max length of path nane } 
SUMaxVNLeng = 24; max length of volume name, includes trailing ‘:* } 
SUM@FNLeng = 15; maximum length of file nane } 
SUVolSuffix = ‘:'; suffix or end of device or volume nane } 
{SENDC} 
TYPE 
SUSet0fChar = SET OF CHAR; 
SUStrP = “SUStr; 
SUStr = STRING [255]; 
SUVoiNane = STRING [SUMaxVNLeng] ; 
{SIFC NOT For0S} 
Pathlicne = STRING [255]; { supply definition of PathNane for Monitor } 
{SENDC} 
SUFile = FILE; 
SUFileP = “SUFile; 
PromptState = (SUDefault, the default (if any) was chosen) } 
SUEscape, the "Clear" key was pressed } 
SUNone, nothing specified in response to prompt } 
SU0ptions, “2" was entered -- ie, an option query } 
SUValid, valid reponse } 
SUInvalid invalid reponse -- eg, non-nunmber to SUGetInt } 
ErrTextRet = (SUO0k, f successful } 
SUBadEF Open, could not open error file } 
SUBadEFRead, { error reading error file } 
rauait deans { error number not found } 
ConvNState = (SUValidN, { valid number } 
SUNON, ' no number -- nothing specified } 
SUBadN, invalid number } 
SUNOverF low { overflow -- number too big } 
VAR 
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{SIFC For0S} 
SU0scotV : SUVolNane; The volune the OS was booted fron } 
SUMyProcV : SUVolNane; The volume };Process was started fron } 
{SENDC} 
SUBe21, SUBs, SUCr, SUTab, SUEsc, SUDle, SUNul : CHAR; f predefined ch vars 
SUNUI1S : SUStr; predefined str var 


{sssssecesessssssssssssssssessss= INIT BND Ch Soscserssessssssssr2sertess2es2rzse=e== 


PROCEDURE SUInit; 
{ Should be called before using rest of wnit. On the OS this opens 
“-KeyBoard". It also initializes the standard character variables. 
te that SUInit sets SUOsBootV and SUMyProcV to null strings, and 
that SUInitSysVols should be called to set them to the correct values. } 


PROCEDURE SUDone; 
{ Can be called when done using unit (although this is not strictly 
necessary). On the OS this closes “-KeyBoard”. } 


FUNCTION SUUpCh (Ch : CHAR) : CHAR; 
{ SUUpCh returns the ch that was passed, uppercased if it was lower case: } 


FUNCTION SULowCh (Ch : CHAR) : CHAR; 
{ SULowCh returns the ch that was passed, lowercased if it was upper case. } 


PROCEDURE SUUpStr (S: SUStrP); 
{ SULowStr uppercases the string that is passed. } 


PROCEDURE SULowStr (S: SUStrP); 
{ SULowStr lowercases the string that is passed. } 


PROCEDURE SUTrinmBlanks (S: SUStrP); 
{ oh ia removes leading and trailing blanks and tabs in the passed 
string. 


PROCEDURE SUAddCh (S: SUStrP; Ch : CHAR; MaxStrLeng : INTEGER; 
VAR OverFlow : BOOLEAN); 
{ SUAddCh appends the passed ch to the end of the passed string. 
OverFlow is set to TRUE if adding the ch will cause the string to be 
longer than MaxStrLeng. } 


PROCEDURE SUConcat (S1: SUStrP; S2: SUStrP); 
{ SUConcat appends the second passed str to the end of the first passed 
string. It is assumed that the target string is of sufficient size to 
acconodate the new value. } 


PROCEDURE SUAddStr (S1: SUStrP; S2: SUStrP; MaxStrLeng : INTEGER; 
VAR OverFlow : BOOLEAN); 
{ SUAddStr appends the second passed str to the end of the first passed 
string. OverFlow is set to TRUE if adding the second string will cause 
the resulting string to be longer than MaxStrLeng. } 


PROCEDURE SUSetStr (Dest: SUStrP; Src: SUStrP); 
{ SUSetStr sets the target string (Dest) to the given value (Src) by 
copying the value onto the target. It is assumed that the target string 
is of sufficient size to accomodate the new value. } 


PROCEDURE SUCopyStr (Dest: SUStrP; Src: SUStrP; Start, Count: INTEGER); 

{ SUCopyStr sets the destination string (Dest) to the specified substring of 
the source string (Src) by copying the appropriate part of the source to 
the destination. It is assumed that the destination string is of 
sufficient size to accomodate the new value, and that the Start and Count 
vaiues are reasonable. } 


} 


Page 
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FUNCTION SUIsVolNane (FN: SUStrP): BOOLEAN; 
{ SUisVolNanme returns a boolean indicating whether the passed file name, FN, 
is a volume or device name (i.e., not a full file name) } 


PROCEDURE SUAddExtension (FN: SUStrP; DefExt: SUStr; 
MaxStrLeng: INTEGER; VAR OverFlow: BOOLEAN); ( 
{ SUHddExtension will add the default extension, DefExt, to the end of the 
file nane, S, if the extension is not already present. If the file nane 
ends with a dot, the dot will be removed and no extension will be added. 
If the pathnane is a device or volume name only no extension will be 
added. OverFlow is set true if adding the extension will overflow the 
string (determined using MaxStrLeng). } 


PROCEDURE SUSplitFN (PathN: SUStrP; VolN: SUStrP; FN: SUStrP; Ext: SUStrP); 
{ SUSplitFN splits a PathName into its volume (device), file name, and file 
nane extension components. } 


PROCEDURE SUMakeFN (PathN: SUStrP; VolN: SUStrP; FN: SUStrP; Ext: SUStr; 
VAR OverFlow: BOOLEAN); 

{ SUMakeFN constructs a PathName from its volune (device), file name, and 
file name extension components. The OS VolN's are assuned to have a 
leading “-", while monitor VolN's are assumed to have a trailing ":”. 
OverFlow is set if any of the file name components are too long. This 
procedure will not create a file nane over SUM@PNLeng chars long. } 


PROCEDURE SUChKFN (FN: SUStrP; VAR PState: PromptState; DefVol: SUStr; 
DefFN: SUStr; DefExt: SUStr); 

{ SUChKFN checks a file name specification, putting result type in PState. 
If no file name is given, then DefFN is used. If FN does not have DefExt 
in it, then the extension is appended. If no volume is specifed then 
the DefVol is used. PState is set appropriately: 


PState = SU0ptions if ‘?' is hit to ask for options 

PState = SUDefault if nothing specified when a default is present 

PState = SUNone if default overriden with ‘\° or if CR with no default 
PState = SUInvalid if one or more of the file name components overflowed ( 
PState = SUValid otherwise } 


PROCEDURE SUGetCh (VAR Ch: CHAR); 
{ SUGetCh reads a character from the console without echoing it and } 
{ without interpreting <cr> as <sp>, as Read (Ch) does. } 


PROCEDURE SUGetLine (S: SUStrP; VAR PState: PromptState); 
{ SUGetLine reads a line from the console a character at a tine, perforning 
its own line editing. PState is set appropriately: 
PState = SUEscape if <clear> was hit. 
PState = SUValid otherwise. } 


PROCEDURE SUGetStr (S: SUStrP; VAR PState: PromptState; DefVal: SUStr); 
{ SUGetStr reads a string from the console; it is like SUGetLine with the 
addition of defaults. PState is set appropriately: 
PState = SUDefault if <cr> only was hit; S is set to DefVal. 
PState = SUEscape if <clear> was the first character hit. 
PState = SUValid otherwise. } | 


PROCEDURE SUGetFN (FN: SUStrP; VAR PState: PromptState; DefVol: SUStr; 
DefFN: SUStr; DefExt: SUStr); 
{ SUGetFN reads a file name fron the console, with result type in PState. 
SUGetFN will print out any defaults in brackets (such as [FOO] [.TEXT]) 
before prompting for for the file name. If no file name is given, then 
DefFN is used. If FN does not have DefExt in it, then the extension is 
appended. If no volume is specifed then the DefVol is used. If only a 
volume name is specified then no default file name or extension will be ( 
added. PState is set appropriately: \ 
PState = SUEscape if <clear> hit 
PState = SU0ptions if ‘7° is hit to ask for options 
PState = SUDefault if nothing specified when a default is present 


eppts computer 
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PState = SUNone if default overriden with ‘\' or if CR with no default 
PState = SUInvalid if one or more cf the file name components overflowed 
PState = SUValid otherwise } 


PROCEDURE SUGetInt (VAR I: INTEGER; VAR PState: PromptState; DefVal: INTEGER); 
{ SUGetInt reads an INTEGER from the console, with PState set as in 
SUGetStr, except that PState = SUInvalid when a non-numeric is input. } 


PROCEDURE SUWaitEscOrSp (VAR PState: PronptState); 
{ SUWaitEscOrSp prints a message ‘Type <space> to continue, <clear> to exit.’ 
& waits for the user to hit a <sp> or <clear>, setting PState appropriately: 
PState = SUEscape if <clear> was hit 
PState = SUValid if <sp> was hit } 


PROCEDURE SUWaitSp; 
{ SUWaitSp prints a message (‘Type <space> to continue. ') and waits for the 
user to hit a <sp>. } 


PROCEDURE SUGetChInSet (VAR Ch: CHAR; Chars: SUSetOfChar); 
{ SUGetChInSet reads characters from the console (without echoing) until 
a character from the given set is typed. The accepted character is echoed 
and an end-of-line is written. } 


FUNCTION SUGetYesNo : BOOLEAN; 
{ SUGetYesNo prints the message "(Y or N)” and reads characters from the 
console (without echoing) until a ‘y’, ‘Y’, ‘n‘, or ‘N’ is typed. Ifa 
‘y' is typed "Yes" will be printed followed by an end-of-line; if ‘n’ is 
typed "No" will be printed. The appropriate boolean value is returned. } 


FUNCTION SUGetBool (Default: BOOLEAN): BOOLEAN; 

{ SUGetBool prints the message “(Y or N) [<default>]" and reads characters 
from the console (without echoing) until a ‘y’, ‘Y’, ‘n', ‘N’, space or 
return is typed. If a ‘y’ is typed “Yes” will be printed in the place 
of the default. If ‘n’ is typed “No” will be printed. If a space or 
return is typed the default is used. The appropriate boolean value is 


returned. } 


PROCEDURE SUGetErrText (ErrFN: SUStr; ErrN: INTEGER; ErrMsg: SUStrP; 
VAR ErrRet: ErrTextRet)-; 

{ SUGetErrText retrieves error message text, given an error nunber and 
and error file to look the error up in. The error file should have 
been generated by the error file processor. SUGetErrText use SUSysReset 
to open the error file. } 


PROCEDURE SUErrText (ErrFN: SUStr; ErrN: INTEGER; ErrMsg: SUStrP); 

{ SUErrText retrieves error message text, just as does SUGetErrText; 
however, if the text is not obtainable due to a non-SUOk ErrRet value 
fron SUErrText, SUErrText will return the string 
“Error message text not available.” } 


PROCEDURE SUStopExec (VAR ErrNunm: INTEGER); 
{ Kiils and exec file on the OS, returns any error conditions in errnunm } 


{SIFC For0S} 
PROCEDURE SUInitSysVols; 
{ Initializes “SUMyProcV" and “SUOsBootV", the name of the volume on which 

My process was created and the name of the volume which the OS was booted 
off of. A message may be printed if there is trouble getting this 
information from the OS. This can be called more than once; it will only 
male the OS calls if SUMyProcV and SUOsBootV are both null strings (as 
they will be after a call to SUInit. } 

{SENDC} 


PROCEDURE SUSysReset (F : SUFileP; FN : SUStr; VAR I0Status : INTEGER); 
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{ SUSysReset is for opening system files, and will try the prefix, boot, 
and current process volumes (in that order) when trying to access a file. 
SUSysReset assumes that the file name FN does not have a volume nane. 
SUSysReset may sometimes have to call SUInitSysVols. } 
sesssssscessstssssssecssseeezecz=== CONVERSIONS SErsrssssssssssssssssssssssssssses} ( 


{ SUintToStr converts an integer into its string form; The string which S 
points to should be of length >= 6 (5 digits + sign). } 


PROCEDURE SULIntToStr (N : LONGINT; S : SUStrP); 
{ SULIntToStr converts an longint into its string form; The string which S 
points to should be of length >= 11 (10 digits + sign). } 


PROCEDURE SUStrToInt (NS : SUStrP; VAR N : INTEGER; VAR CState : ConvNState); 
{ SUStrToInt converts a string to an INTEGER. Leading and trailing blanks 
and tabs are permitted. A leading sign [‘-*, ‘+’] is permitted. The 
CState variable (conversion state) will be set to indicate if the nunber 
was valid, if no nunber was present, if am invalid number was specified, 
or if the nunber overflowed. } 


PROCEDURE SUStrToLInt (NS : SUStrP; VAR N : LONGINTI; VAR CState : ConvNState); 
{ SUStrToLInt converts a string to a LONGINT. It behaves just like 


dl 

PROCEDURE SUIntToStr (N : INTEGER; S : SUStrP); | 
SUStrToInt otherwise. } 
| 
| 


Rich Page 
Apple Computer, Inc. 
May 4, 1983 


Byecution Environment of the Lisa Pascal Compiler 


Registers: 
DO0-D2/A0-Al User temporaries 


 DOD3/A0-A2 Compiler temporaries 
_ D4D7/A3-A4 Compiler uses for locals & pointers 


AS Pointer w global frame 

A6 Painter to focal frame 

Al Pointer 10 top of stack 
Global Frame: 

The global frame consists of two segments: 


1) The Jump Table Segment 
2) The Stack Segment (first of N segments) 
The global frame is layed out as follows: 


Jump Table 
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The Jump Table is a an array of 6 byte JMPs used to 
transfer control between segments of the program and 
the regular units used by the program. This is built by 

- the Linker from Entry paints and Externals reference lists. 


| The Segment Table is a structure which defines each of 
the segments of the program and the regular units. This — 
is used by the Loader to swap in segments. For each of 
“the segments, the Segment Table provides a file address, 
Seed oe 
|. -@ddress (ie. segment number). 


The Data Pointer Table is an array of 4 byte painters 
which is used to reference global data for intrinsic units. 
This pr is built by the Loader and referenced by 


- Compiled code. 


"The Shared Main Program Parameters is an area reserved 
. for use by the Loader to store information about the main 
_ .. . program. Currently this area is $100 bytes. 
The Private Main Program Parameters is an area initialized 
by the loader and referenced by compiled code. This area 
contains pointers to INPUT and OUTPUT file buffers and 
other information such as the size of the regular unit globals. 
Currently this area is $100 bytes. 


The Main Program Globals is the global data allocated by 
the compiler for the program. 

The Regular Unit Globals is the combination of all global 
data required by the regular units used by the program. 
The Intrinsic Unit Globals is the private global data which 
is required by the intrinsic units used by the program. 

The Users Dynamic Stack is that area which is used by the 


program for local frames, temporary data and procedure 
linkages (both pascal and assembly language). 


Initially the Loader allocates enough space to cover these 


areas and the user min stack requirements. The system also. 
’ enforces a upper limit (ie. max stack). 
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Local Frame: 
The local frame consists of the following: 
1) Function result and parameters 
2) Static and dynamic links 
3) Locals and compiler temporaries 
7 4) Dynamic stack area 
_. The local frame is layed out as follows: 


Dynamic Stack Area 


"'® Two of four byte function result, present only for functions. 
** N bytes depending on the parameter list. 
.°** Present only for non level 1 procedures and parameters. 


The local frame is allocated by the compiler and allows the 
‘compiled code to reference locals, paramters, static links, .. 


The dynamic link (ie. O1dA6) is pushed by the LINK A6 
instruction which allocates space for locals and compiler temps. 


The static link is pushed by the caller as part of the parameter 
ist. The static link is a copy the parents A6 (ie. local frame). 


Compiler temporaries are used to implement constructs such 

as non local gotos and expressions computed by the compiler 
which happen to not be in registers. These expressions may 
include for loop limits or with expressions, 


Parametric procedures and functions appear as follows: 


Address of proc/func body 


Note zero is used for level 1 procedures. 
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Automatic Stack : 


‘The compiler communicates the space requirements for each 
procedure by preceding each LINK A6,# -size with one of the 


following sequences: 
« TST.W oe(A7) 
OF é 2 
MOVEL AT AO 
SUBL #size,A0 
TST.W (AO) 


The offset used in the first case or the size in the second reflect 
the sum of the procedures static and dynamic requirements. 

This sum is inflated by at least $100 bytes to allow assembly 
language procedures to use a small amount of stack space at 7 
low cost (ie. they need not check). Note the code for automatic 
stack expansion can be controlled with a compile option. 


JSRs, JMPs, LEAs and PEAs: 


' ‘These instructions are used to transfer control and obtain the 
address of a procedure or function. These instructions exist in 
three forms all of which occupy 4 bytes each: 


1) Within a segment: PC relative 
_ 2) References to regular segments: Offsets from AS 
3) References to intrinsic segments: IU Trap instructions 


The first form is simply a reference to a procedure from within © 
the same segment which uses the PC relative addressing mode. 


The second form is a reference to a procedure which is not in 
the same segment but is contained in a segment of the program 
or a regular unit. This is implemented by using an offset from 
AS to reference the procedure through the Jump Table. 


The third form is a reference to a procedure which is contained 
in an intrinsic segment (ie. in an intrinsic unit). This form is 
implemented by using Line 1010 trap mechanism to compress 
the opcode and 24 bit logical address into a 4 byte instruction. 


In each of the above cases the compiler emits references the 
desired procedure or function and the linker constreuts the 
appropiate addressing mode for JSRs, JMPs, LEAs and PEAs. 
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Structure of Code for a Pascal Procedure or Function: 


The code emitted by the compiler contains three constructs which 
can be controlled via compile time options. These are as follows: 


1} Automatic stack expansion. 
2) Range checking for values, indexes and strings. 
3) Debuggung info Ge. the procedure name). 


The coe for a pial prsedue wil ak sows: 


‘TST.W = e(A7)_—«—SS—CS—Ss*TTests fo sufficient stack space 
LINK A6, #-size Allocates space for locals 
body of the procedure or function 
AG Restores previous local frame 
 _. ° Bait sequence 
Bight byte procedure name and 
two byte data size. This is the 
optional debugging information. 
| conan aaa or ings & 


The exit sequence emitted by the compiler is dependent on the 
number of bytes of parameters. If there are no parameters then 
the RTS is used as shown above. The compiler emits one of the 
following sequences when parameters must be deleted: 


Case #1: 2, 6 or 8 bytes of parameers 


MOVEL (AZ)+ ,A0 2 
ADDOQ.W #size,A7 2 
JMP (At) + 
Case #2: 4 bytes of parameters eee 
MOVEL (A7)+ {AD 2 
RTS + a 
Case #3: more than 8 bytes of parameters = 
MOVEL (A7)+ ,A0 2 
ADD.W #size,A7 4 
JMP (AQ) 2 
S bytes total 
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Se ntation & constants d by value: 


Since the 68000 is not restartable, (ie. use a 68010 instead) the 
data (ie. stack and heaps) for a given program must be present 

. while the program is executing. Since code segments must be 

_ swapped into memory as needed and set and string constants 
fe stored with the code, large constants passed by value pose 

@ problem. Currently, we solve this problem by having the 

~~ compiler use the instruction TST.B (Ai) wo check wo see if the 

. the actual value parameter is in memory. If the TST.B (Ai) 
Causes a fault then the system loads the segment containing the 

“address in Ai. | | | 


When copying strings the compiler emits code which depends 

_ Only on the size of the destination. This may cause the code 
to read beyond the end of a segment. The system allows for 
this by mapping code segments to cover size + 256 bytes. The 
heap segments also have an additional 256 bytes. 
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Intrinsic Units 


AQOTE: The information in this document will be in the Units section of the Fascal 
Manual in the spring release. 


Intrinsic units provide a mechanism for Pascal programs to share common code. A 
single copy of the code is kept on disk, and when loaded into memory this code can 
be executed by any program that declares the intrinsic unit (via a uses clause, just as 
for regular units) and has been linked against the library file. In addition, a shared 
intrinsic unit provides for the sharing of common data (i.e., one copy of the data on 
the system). 


The code of the entire unit, or of blocks within the unit, must be placed in one or 
more named segments. Segmentation is controlled by the $S cornpiler command 
(described in the Fascal Fleference Maral), the ChangeSeg utility, and the +M linker 
option (both described in the torkshop Ler’s Guide). Code from an intrinsic unit 
cannot be placed in the same segment with code from a4 program or & reguler unit. 


Writing Intrinsic Units 


An intrinsic unit has the same syntax as a regular unit, except that it has an intrinsic 
clause in the heading. 


NOTE: For syntactic compatibility with UCSD Pascal, the keywords code and data 
may appeer in the unit heading of an intrinsic unit, together with integer 
constants. These keywords and constants are accepted but are ignored. 


If the keyword shared appears in the intrinsic clause, the system will contain only a 
single data area for the unit; the data is shared among all programs that use this unit. 
If shared does not appear in the intrinsic clause, each program that uses the unit has 
its own data area for the unit. 


If an intrinsic unit contains & uses clause, it can only use other intrinsic units, an 
intrinsic unit cannot use & reguler unit. — 


Each unit used by @ program (or by another unit) must be compiled, and its object file 
must be accessible to the compiler, before the program (or unit) can be compiled. 


A single copy of the code of an intrinsic unit is available to all programs in the 
system; therefore, intrinsic units must be coordinated as part of system generation and 
systern maintenance activities. Specifically, all intrinsic units that have code in the 
same run-time code segment file must be linked together into an intrinsic segrnent 
file, and the intrinsic segment file must be referenced in the system intrinsics library, 
INTRINSIC.LIB. 
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Building Library Files 
To create intrinsic units and link them into a library file, you must perform the 
following steps in order, as shown in Figure 1: 
step la Compile and Generate the intrinsic units. 
step 1s Define the intrinsic units, code segments, and file names, using the 
IUManager. (Steps 1a and is can be done in either order.) 
step 2 Link the intrinsic libraries. 
srep 3s Install the library files, using the [UManager. 
step 4 Develop the main prograrns (not shown in detail). 
step 5 Run main programs which use the library files. (The systerm must be 
rebooted before this step.) 
step is |‘), 
' 
Figure 1 
Developing Intrinsic Libraries 
io: | 
fete) Crie >) into nov, 
RUN : 
STEP 5 ( 
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The IUManager 


(For versions 1.x and 2.x software) 


Tne IUManager progrem is used to manage the directory of library files. You 
can add, delete, or change intrinsic units, segments, and files in the 
directory. To use the IUManager, you should be femiliar with the way that 
units and segments are handled in Pascal on the Lisa. (Information on 
intrinsic units is in the Intrinsic Unit ERS by Ken Friedenbach from September 
16, 1981.) This document describes the version of the IUManager in software 
prior to the “spring release". 


The IUManager has three modes, which do the following: 


Units: Add, delete, or change intrinsic units. An intrinsic unit is 6 
unit of Pascal code that can be accessed by different 
processes. There are two kind of intrinsic units--regular and 
shared. fA regular intrinsic unit has a private global data 
area associated with it: shared intrinsic units share data as 
well as code. 


Segments: Add, delete, or change segments. Units can be broken up into 
segments, so that interdependant parts of different units will 
be swapped in and out of memory at the same time. You can 
segment your code with either the $S Compiler option or the 
ChangeSeg utility. 


Files: Add, delete, or change library files. Units and segments are 
erranged in library files. 


When you run the JUManager, you are asked the input and output names of the 
library directory that you want to edit. The default name for both is 
INTRINSIC.LIB, the directory that the system looks for at boot time. (Don't 
play with the INTRINSIC.LIB unless you know what you're doing, or your system 
may not boot!) 


When you first enter the IUManager, you're in the segments mode. The 
IUManager has only one command line, so if you don't know which mode you're 
in, either L({ist the current table or type S({egs, U(nits, or Fliles to get to 
the mode you want. The commands available in the IUManager are: 


O(uit Quit the TUManager and rewrite the directory. 
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S(egs Select the segments mode and list the segnent table. Entries in 
the segment table have the following information: 
SEGMENT The segment name. 
NUM The segment number (17-128). 
F—NUM The number of the file that the segment is in. 
F-LOC The byte location of the segment in the file. 
PACKED/ 
UNPACKED The number of packed or unpecked bytes in the segnent. 
FILE-NAME The neme of the file that the segment is in. 
U(nits Select the units mode and list the unit table. Entries in the 
unit table have the following information: 
UNIT The unit neme. 
NUM The unit number (1-256). 
F—-NUM The number of the file that the unit is in. 
TYPE The type of unit: Intrinsic or Shared Intrinsic. 
DATA-SIZE The number of bytes of global data (Shared Intrinsic 
units only). | 


FILE-NAME The neme of the file that the unit is in. 


F(iles Select the files mode and list the file table. Entries in the 
file table have the following information: 


NUM The file number (1-64). 
FILE The file neme. 


I(ns Install a library in the directory. This stores the segment and 
unit tables from the linked object file. The Install command puts 
you in the files mode if you're not in it already, lists the file 
table, and prompts you for the file number to install. 


L(ist List the entries in the currently selected table. Use @-S to 
stop the output for tables of more than 32 entries. 


P(rt Print all three tables. This command doesn't work. If you accept 
the default [PRINTER:], the tables are not printed, but are sent 
to a file named PRINTER:. To print the tables, send them to a 
-TEXT file (or change the PRINTER: file to a .TEXT file), and 
print them from the Editor. 
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R( em Remove an entry from the currently selected table. You ere 
prompted for the segment, unit, or file number. If you try to 
remove a file that is used by the segment table, you will get a 
warning, and the file will not be removed. 


C(hng Change an entry in the currently selected table. You will be 
asked for the segment, unit, or file number, and prompted for 
changes in each field. If you enter an unused number, the Change 
command works just like the New command. If, in changing a unit 
or segment, you specify a file name that has not been used, a new 
file will be created with the next available file number. 


N( ew Create a new entry in the currently selected table. You will be 
asked for the segment, unit, or file number, and prompted for each 
field. If you enter a number already associated with an entry, 
the New command works just like the Change command. The default 
entry number is the first unused number in the table. Yalid 
ranges for entry numbers are: 


Segments 17 - 128 
Units 1 - 256 
Files 1- 64 


NOTE: Segment numbers 1-16 are used by the OS, but the IUManager 
doesn't know this, and prompts you for them. DO NOT USE 
THEM, or unspecified evil things will happen. 


If you add a unit or segment and specify a file name that has not 
been used, a new file will be created with the next available file 
number . 


V(erify Verify that the information in the linked object file is 
consistent with the directory. 
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The IUManager 


(For Apple pre-release version 3.x software) 


The IUManager utility is used to manage the directory of library files. You 
can add, delete, or change intrinsic units, segments, and files in the 
directory. To use the IUManager, you should be familiar with the way that 
units and segments are handled in Pascal on the Lisa. (Information on 
intrinsic units is in the Intrinsic Unit ERS by Ken Friedenbach from September 
16, 1981.} This document describes the internal pre-release version of the 
IUManager in the “spring release", which is liable to change without notice 
(though not significantly) . 


The IUManager has three modes, which do the following: 


UNITS: Add, delete, or change intrinsic units. An intrinsic unit is a 
unit of Pascal code that can be accessed by different 
processes. There are two kind of intrinsic units--reguler and 
shared. & regular intrinsic unit has a private global data 
area associated with it; shared intrinsic units share data as 
well as code. 


SEGMENTS: Add, delete, or change segnents. Units can be broken up into 
segments, so that interdependant parts of different units will 
be swapped in and out of memory at the same time. You can 
segment your code with either the $S Compiler option or the 
ChangeSeg utility. 


FILES: Add, delete, or change library files. Units and segments are 
arranged in library files. 


When you run the IUManager, you are asked the input and output nemes of the 
library directory that you want to edit. The default name for both is 
INTRINSIC .LIB, the directory that the system looks for at boot time. (Don't 
play with the INTRINSIC.LIB unless you know what you're doing, or your system 
may not boot!) 
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When you first enter the IUManager, you're in the FILES mode. To switch 
between modes, the following commands are available: 


S(egments 


U({nits 


F(iles 
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Enter the SEGMENTS mode and display the segment table. 
Entries in the segment table have the following information: 


SegNeme 
Seat 
File# 
FileLoc 


Packed/ 
UrPacked 


FileName 


The segment name. 

The segment number. 

The number of the file that the segment is in. 
The byte location of the segment in the file. 


The number of packed or unpacked bytes in the 
segment . 


The neme of the file that the segnent is in. 


Enter the UNITS mode and display the unit table. Entries in 
the unit table have the following information: 


Uni tName 
Unit# 
Filet 
Type 
DataSize 


The unit name. 

The unit number. 

The number of the file that the unit is in. 

The type of unit: Intrinsic or Shared Intrinsic. 


The number of bytes of global data (Shared 
Intrinsic units only). 


( 


Enter the FILES mode and display the file table. Entries in 
the file table have the following information: 


File 
FileName 


The file number. 
The file neme. 


( 
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Other than the S(egments, U(nits, and F(iles commands, the commands available 
in all three modes are the same: 


C(hange 


A( dd 


D(elete 


I(nstall 


V(erify 


P(rint 
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Change an entry in the currently selected table. You will he 
asked for the file, unit, or segnent number, and prompted for 
changes in each field. If you enter an unused number, the 
Change command works just like the Add command. 


Add a new entry in the currently selected table. You will be 
asked for the file, unit, or segment number, and prompted for 
each field. If you enter a number already associated with an 
entry, the Add command works just like the Change command. The 
default entry number is the first unused number in the table. 
If you add a4 unit or segment and specify a file neme that has 
not been used, a new file will be created with the next 
aveallable file number. 


Delete an entry from the currently selected table. You sre 
prompted for the file, unit, or segment name or number. If you 
try to delete a file that is used by the segment table or unit 
table, you will get a warning, and the file will not be 
removed. If you try to delete a segment that is used by the 
system table as a Public Interface segment, the segment will 
not be removed. 


List the entries in the currently selected table. 
Quit the IUManager and rewrite the directory. 


Typing ? from the main command line displays the alternate 
command line, with the following commands: 


Install a library in the directory. This stores the segment 
and unit tables from the linked object file. The Install — 
command puts you in the FILES mode if you're not already, 
displays the file table, and prompts you for the file name or 
number to install. 


Verify that the information in the linked object file is 
consistent with the directory. You are prompted for the name of 
the file to verify. 


Print all three tables. (You can send the tables to a .TEXT 
file oe of -PRINTER if you want to look at them in the 
Editor. 


Typing ? from the alternate command line returns you to the 
main commend line. 
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Lisa Object File Formats 


1.0 Introduction 


This document provides a detailed reference manual for the object file formats 
and system conventions which define the software run-time environment for Lisa 
Applications. This information is of use to developers of compilers which 
emit object code to be linked with the IULinker. Object code which is in 
these formats can be executed under the Monitor or the 0.S. Loaders or be 
debugged with LisaBug. Fred Forsman is currently working on a Symbolic 


Debugger which will assume these formats. Some of this information will be of 
use to third-party software developers who develop libraries of Intrinsic 


Units to support specialized applications. This information may be of use to 
programmers who develop and debug programs at the machine or assembly language 
level. 


This document describes a set of Intrinsic Units used by programs in the 
Pascal Development System which create and access object files. These units 
are useful in building utility programs which can be maintained across changes 
in object file formats. The units are distributed in the library file named 
ObjJIOLib.OBJ. The ObjIOLib units are used by the Pascal Compiler, the Code 


Generator, the Assembler, the Monitor Loader, the IULinker, the IUManager, and 
a variety of utility programs including DumpObj, ChangeSeg, GXRef, SegMap, 
CodeSize, PackSeg, and ReUse. The units will be used by the Symbolic 
Debugger. Information on the functions and use of the above programs is 
contained in the Pascal Development System Manual. 


Developers of Code Generators are strongly urged to use the ObjIOLib units for 
writing object files and developing object file utilities. This will reduce 
maintainence difficulties caused by object file format changes. 


This document describes the object files in their present form (Monitor 
Release 10, 0.S. Release 5.2). Except for additions in the area of Symbolic 


Debugging, this form should be the formats for First Release of the Lisa 


Office System. In some places in the document, future changes or extensions 
are mentioned. This information is tentative and is primarily intended to aid 


in long range planning for maintenance. 


1.1 Related Documents 


The reader is assumed to be familiar with the following documents: 


PASCAL DEVELOPMENT SYSTEM MANUAL, Bill Schottstaedt, February 16, 1982. 
Sections of relevance are: The Linker, Segmentation and Intrinsic 


Unit Management, and Object File Debugging. 


PASCAL DEVELOPMENT SYSTEM INTERNAL DOCUMENTATION, Bill Schottstaedt, 
February 16, 1982. This document is an expansion of the sections: 
Linker File Layout and Jump Table Formats. 
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LISA PASCAL: LANGUAGE SPECIFICATION, Rich Page and David Casseres, 
February 19, 1982. Background material is contained in Section 
14; UNITS. 


LISA HARDWARE REFERENCE MANUAL. Especially the sections on Memory 
Mapping and address translation. 


LISA OPERATING SYSTEM REFERENCE MANUAL. Especially the description of 
the loader (task initialization) and the flushing of INTRINSIC.LIB. 


1.2 Overview of the Lisa Hardware/Software System 


The Lisa Hardware supports the mapping of a 16 M-byte logical address space 
into a smaller physical address space at run-time. The 16 M-byte logical 
address space is divided into 128 (logical) segments of 128 K-bytes each. 


The IULinker supports Intrinsic Units (shared code) by linking main programs 
and intrinsic units into absolute locations in the 16 M=-byte logical address 
Space. The system Loaders support the execution of programs which use 
Intrinsic units by swapping code into memory, setting up a Memory Management 
Unit (MMU) to translate logical adrreses into physical addresses, and handling 
the sharing of code between different programs (processes). 


Uniform addressability of code is achieved by assigning an MMU number (128 


K-bytes of logical address space) to each Intrinsic Unit segment. Code 
segments for a Main Program are assigned MMU numbers which are not among those 


assigned to Units used by the program. 


Uniform addressability of data areas for Intrinsic Segments is achieved via 
pointers which are at a fixed location relative to the Global Frame pointer 


(register A5). This allows a “compact” allocation of global variables for 
Intrinsic Units without “holes” for Units which are not used. 


Unlike UCSD Pascal the assignment of numbers to Segments and Units is done at 
Link time, not at compile time. Only Symbolic names are assigned at Compile 
Time. Also, the control of Segmentation is much more flexible than in UCSD 
Pascal. Procedures from different Units can be combined into the same 
segment. 


Short Jumps (4 bytes rather than 6 bytes) to Intrinsic Unit Segments are 
achieved via emulated instructions. These instructions are editted by the 
IULinker. They make use of the “Axxx" class of emulation instructions 
supported by the hardware. See the section on the Intrinsic Unit Trap Handler 
in the PASCAL DEVELOPMENT SYSTEM INTERNAL DOCUMENTATION for more details. 


Current instructions emulated include: 


IUJSR -- JSR to an IU Segment procedure or function. 
IUJMP — JMP to an IU Segment procedure or function. 
IULEA -- LEA of an IU Segment procedure or function (except into A7). 
IUPEA -- PEA of an IU Segment procedure or function. 
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The major advantages of this architecture are the following: 


One copy of code (on the disk and in memory) can be part of several 
different programs. 


Code can be swapped into memory in a state that is "ready to execute”. 
No patching or load-time linking is needed. 


Since code segments are “read only" code never needs to be swapped out. 
(However, debuggers must be aware of swapping to reinstall breakpoints.) 


Some of the disadvantages are: 


The size of the Intrinsic Unit library is limited by the number of MMU’s 
supported by the hardware. (This could be expanded by treating the 
library as a tree structure or by swapping related segments and mapping 
them with a single MMU.) 


The size of the largest program using Intrinsic Units is limited by the 
number of MMU”s supported by the hardware. 


There is a slight performance penalty in accessing global variables in 
Intrinsic Units indirectly via the table of pointers. (The Pascal 
Compiler puts such references into the pool of computations to optimize 
by saving results in registers.) 


There is a penalty in speed in emulating the instructions IUJSR, IUJMP, 


IULEA, and IUPEA. For the most common instruction (JSR) the penalty is 
about 8:1 for the emulated version. This causes an overall 2:1 increase 


in the average procedure overhead (including LINK, UNLINK, return, 
argument passing and scrubbing, saving optimization registers, automatic 
stack expansion, etc.) 


1.3 Basic Definitions 


Segment 


This term is used in two different senses which are related but distinct. 

From the hardware point of view, a segment is a portion of the logical address 
space which is mapped by an MMU and can include from 0 to 256 blocks of 512 
bytes (zero to 128 K bytes). From the software point of view, a segment is a 
swappable piece of code of up to 32 K bytes. (The 32 K limitation is related 
to using signed words for PC relative branches.) There are also special 
segments, such as the stack segment and the jump-table segment. Where the 
distinction is important, the terms “logical segment” and “code segment” will 
be used. 


Module (Block) 
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A module or block is a contiguous piece of memory. In unlinked files produced 
by the Pascal Compiler, a module is a procedure or function including string 
constants, set constants and embedded debug information. In unlinked files 
produced by the Assembler, a module is a single .PROC or .FUNC section of 


code. The IULinker also defines several other blocks of memory which are 
referenced and defined implicitly by the languages and run-time environment: 
the “global data” area (or initial stack), the “data pointer” area for 
accessing the global data of intrinsic units, and the jump table of a Main 
Program. The heap is the only part of the run-time environment which the 
Linker does not define as a block. 


In a linked file, a block is a code segment (i.e. the smaller blocks of memory 
have been bound together into a larger contiguous piece of memory). Code 
modules (whether linked or unlinked) are represented in an object file by a 
set of object file records, beginning with a ModuleName block and ending with 


a EndBlock. 


Note: the use of the term “module” to mean a “block” is due to historical 
roots. At some time in the future it would be nice to switch to the following 
terms, although this will involve massive edits to existing programs: 


Block -- a contiguous piece of memory. 

Module -- a block of data and one or more blocks of code. 

Class -- a Module which can be instantiated with several data blocks. 
Segment -- code blocks of one or more modules linked together. 
ObjRecord -- a file format. 


1.4 Types of Object Files 


A object file contains one or more records of information relating to the 
execution of machine code. There are several types of object file: 


Intrinsic Unit Directory (IUDirectory) 
Intrinsic library and Main Program 
Unlinked Units and Code 


The general function of each type of object file is discussed below. The 
detailed specification of which blocks are present is given in the Section 
7.0. Detailed formats of each block are given in Appendix A. 


Intrinsic Unit Directory (IUDirectory) 


Intrinsic Unit Dircectories are read and written by the IUManager. The 
“current” or “active” directory is found by convention in the file 
INTRINSIC.LIB on the 0.S. boot volume or the Monitor root volume on the 
working device. Loaders read INTRINSIC.LIB to locate Intrinsic Segments. The 


IULinker uses INTRINSIC.LIB to compute the transitive closure of Intrinsic 
Units referenced and to assign absolute logical addresses. The Compiler reads 
INTRINSIC.LIB to locate the interfaces of Intrinsic Units. 
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Intrinsic Library and Main Program Files 


Intrinsic library and main program files are written by the IULinker and 
loaded for execution by loaders on the Monitor and the 0.S. Intrinsic library 
files contain linked intrinsic unit code which is ready to be loaded and 
executed as part of a main program. In addition, Intrinsic library files may 
contain linker information and unit interfaces used in the compilation and 
linking of other units and main programs. Intrinsic library and Main Program 
files can be stripped and packed by the PackSeg Utility in order to minimize 
disk space in a production system. 


In the present development environment, the IUManager must be used to define 
Intrinsic Segments and Intrinsic Units before the IULinker links them. After 
the IULinker has linked an Intrinsic library file, the Intrinsic library file 


must be "Installed" using the IUManager. The installation operation places 
file relative location information in INTRINSIC.LIB so that the loaders can 


efficiently locate and load segments. 
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2.0 Grammatical Definition of Object Files 


The grammar used is a form of Extended BNF similiar to that used by Wirth in 
describing Modula-2 [1]. The major differences are the adoption of a 
“list-of" construct suggested by DeRemer [2] and the interpretation of {E} as 
one or more occurances of E. The Extended BNF is capable of describing itself 
concisely: 


Syntax 
syntax = {production}. 
production = NTSym "=" expr ".” 
expr = <term "|" >. 
term = {factor}. — one or more factors 
factor = TSym | NTSym | "(" expr ")" 
| "“{" expr ")" | “<" expr TSym ">" 
| "{" expr "}". 
Semantics: 
El | E2 denotes either El or E2 
that is, one of two alternatives. 
{E} denotes E, EE, EEE, etc. 
that is, one or more E’s. 
{E] denotes the empty string or E 
that is, an optional E. 
<E P> denotes E, EPE, EPEPE, etc. 
that is, a list of E’s separated by P’s. 
( ) are used for grouping. 
NOTE: [{E}] denotes the empty string, E, EE, EEE, etc. 
Scanning: 


Lid ee 


Comments are delimited by "“=--" and the end-of-line. 
Special character terminals are in quotes. 
The string : 


00 O09 ce ee 


is a quoted “. For example: 
The sentence: “It’s hot today!", he said. 
would be quoted: """It°s hot today!"", he said.” 


Conventions: 
Syntactic class names begin with a lower case letter. 
Terminal class names begin with an upper case letter. 


Object file formats are descibed in the form used by the Development 
System during the development and testing of software. The “stripped and 
packed” formats produced by the PackSeg utility are documented in the 
comments. The PreLink file formats are also mentioned a few places in the 
comments, but have not been completely specified. 
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2.2 SOFIWARE CONFIGURATION FILES 


objFile = 
iuDirectory | sysPackTable 
| iuLibrary | mainProg 
| unlinkedUnit | unlinkedModule. 


iuDirectory = 
VersionControl UnitLocation SegLocation FilesBlock 
[CodeBlock] EOFMark. 


sysPackTable = VersionControl PackTable EOFMark. 


The iuDirectory defines the intrinsic units and intrinsic segments 
which are available for use by main programs. By convention the name of the 
active iuDirectory is INTRINSIC.LIB. The optional CodeBlock contains the IU 
Trap Handler for the 0.S. without LisaBug. This file cannot be packed. 


The sysPackTable file contains the PackTable record used in packing 
any intrinsic library or main program files on the 0.S. By convention the 
active PackTable is in PACKTABLE.LIB. This file cannot be packed. 


2.3 LINKED FILES 


iuLibrary = 
VersionControl SegLocation 


[InterfLocation] -- stripped. Present if Interfaces in file. 
UnitTable SegmentTable -- stripped, only used by Linker 
{UnitBlock} -- interfaces are stripped 


{iuLibModule} EOFMark. 


iuLibModule = 
ModuleName 


[{EntryPoint}] -— stripped 
[{CommonReloc | ShortExternal}] -- later, to support PreLink 
CodeBlock EndBlock. 


mainProg = . 
VersionControl [UnitTable] Executable [SegmentTable] 
{module} EOFMark. 

module = ModuleName {otherModBlock} EndBlock. 


otherModBlock = 
EntryPoint | StartAddress | CommonReloc | ShortExternal 
| CodeBlock | Relocation | External. 
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The SegLocation block in iuLibrary files is for future Loader support 
of slightly different versions of files on a system, i.e. packed Lisa Office 


System files and Development System versions with interfaces and linker 
information. Presently, one set of numbers is installed in INTRINSIC.LIB and 


is assumed valid for any file of the indicated name. 


The InterfLocation block is used by the Compiler to quickly access 
interfaces in the UnitBlock(s). The UnitTable and the SegmentTable contain 


the transitive closure of intrinsic units used and intrinsic segments from 
code within a file. The UnitTable and SegmentTable are only present if 


intrinsic units are referenced. 


The UnitBlock contains the size of the global data area for a 
particular intrinsic unit and optionally the interface or interface location 
information. 


Presently iuLibrary modules do not contain relocation records. 


However this is planned for the PreLink and InstallLink programs which will 
support third party software development and distribution. 


The Executable block contains the segment table and the jump table for 
the main program and regular unit segments. 


unlinkedUnit = 
-- later: VersionControl 


UnitBlock 

{ {module} ] -- units can be definitions only 
EOFMark 

TextBlocks. —- note: TextBlocks after EOFMark. 


unlinkedModule = 
-- later: Version Control 
{module} EOFMark. 


An unlinked unit file is the output of a compiler which is intended 
for “use” or “import” by another compilation. The kludge of having text 
blocks tacked on the end of the file is scheduled for replacement by 
compilation to an intermediate form which includes definitions. 


A unlinked file is formed by a compiler or an assembler. Version 
control blocks are not presently placed on unlinked files but are sheduled to 
be shortly added (11.0). 
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3.0 Future Directions 


3.1 Version Control 


Version control will be needed for two purposes: 


To prevent the execution from inconsistent library and main program 
files. 


For consistency checking of a software configuration, i.e to support the 
Make facility and the Software Management Utility. 


Version control for execution is scheduled for implementation after the second 
product build (internal use). 


3.2 The Software Management Utility 


A Software Management Utility is being developed which will facilitate the 
management of system dependencies and the automatic regeneration of a system 
based on consistency checking. This facility represents an extension of the 
UNIX “make” facility to include: 


Distinction between interface and implementation editing changes. 
Distinction between linking with regular units (code is copied) and 


intrinsic units (code is referenced). 
Support for the concept of “reuseable” intrinsic library files. 


Support for the concept of a “run-time” library directory. 


The Software Management will provide for management of four levels of system 
implementation and configuration: 


Run-time Systems 

Intrinsic Library Files 
Unlinked or Raw Object Files 
Source Code Files 


3.3 Symbolic Debugging 


A new attempt at defining and implementing a Symbolic Debugger is being made. 
In the previous effort, the emphasis was on dumping symbolic information from 
the compiler into an independent .DBG file. In the current effort we are 
examining the possibility of passing more information through the .I-code file 
to the code generator. Some forms of debugging information will be embedded 
in the CodeBlock. Other forms of debugging will be introduced as new block 
types. 


3.4 Other Languages 
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Currently we are planning for COBOL to generate object files which can be 
linked with the IULinker. We are also investigating the feasibility of 
bringing Modula-2 up on Lisa. Over the course of the next year Lisa will 
begin to support multi-language development projects. 
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4.0 Object Record Details 


Object file records consist of a Header, an Invariant part and a Variant 
part. 


The Header consists of a byte which indicates the BlockType followed by a 
three byte length field. The GetObjInvar and PutObjInvar procedures in ObjIO 
manage the details of the BlockType encoding and translate the particular 
encoding into an enumerated type. 


The Invariant part is always a fixed length (possibly zero) for a given 
BlockType.- The Invariant part characterizes the record. The following 
BlockTypes are currently supported: 


BlockType= 
(ModuleName, EndBlock, EntryPoint, 
External, StartAddress, CodeBlock, 
Relocation, CommonReloc, 
ShortExternal, 
UnitBlock, InterfLoc, 
Executable, VersionCtrl, 
SegmentTable, UnitTable, SegLocation, UnitLocation, FilesBlock, 
PackedCode, PackTable, 
EOFMark) ; 


Note: the current ObjIO Unit includes some additional BlockTypes that are 
supported for compatibility reasons, but are not intended for future support. 


For each of the above BlockTypes there is a corresponding invariant record 
definition in ObjIO. For instance, the BlockType "“ModuleName” has an 


invariant record definition "iModuleName”. These are shown in detail below. 


The Variant part may be missing, optional or of varying length depending on 
the BlockType. When present, the Variant part of an object file record 
usually consists of a varying number of fixed size entries. There are 
exceptions, however, such as the Executable block which has a complex variant 
structure (segment table, jump table and a few miscellaneous entries). The 
following VariantTypes are currently supported: 


VariantType= 
(NoVariant, 
RefVariant, ShortRef, ModVariant, Comments, 
SegVariant, UnitVariant, IntfLocVariant, 
SegLocVariant, UnitLocVariant, FilesVariant, 
JumpTVariant, JTSegVariant, ObjectCode); 
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The association of a VariantType with each BlockType is expressed in two 
ways. In the invariant record definition a comment at the end documents the 
corresonding VarinatType. In addition, there is an array of information in 
ObjIO which contains the mapping. GetObjInvar and PutObjInvar manage the 
communication of this information to programs accessing object files. 


In the definition of object file records, there are some standard types used 


in addition to Integer, LongInt, Boolean, Char, etc. The following types are 
introduced in the indicated Units: 


(* from Unit PasDefs: *) 


const NameStrLen = 8; (* Length of Identifier Names *) 
MaxLStringLen = 80; (* Reasonably long: error messages etc. *) 


type NameString = packed array [1..NameStrLen] of char; 
LString = String [MaxLStringLen]; 


MemPtr = “integer; (* “untyped” pointer to memory *) 
ProcPtr = “integer; (* in place of Procedure variables *) 


(* from Unit ObjIO: *) 


type FileAddr = longint; (* 0 based, byte address within a file *) 
MemAddr = longint; (* 24-bit virtual address *) 
SegAddr = longint; (* O based, byte address within a segment *) 


Note: the name of the type NameString may need to change in the future due to 
a conflict with a different type in the 0.S. and the lack of support for 
qualified names in Pascal. 


4.1 VERSION CONTROL 
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VersionCtrl: 


penne tt 


| 99 | size 


iVersionCtrl = record 


SysNum, MinSys, 


MaxSys, Reservl, 


Reserv2, Reserv3: longint; 


end; 


| SysNum] MinSys| MaxSys|Reserv1|Reserv2|Reserv3| 


mt ttt tt ttt ttt tt tt ttt ttt 


1 2 


MaxSys 
Reservl 
Reserv2 


Reserv3 
Note: 


5 


9 13 17 21 25 28 


Hexadecimal 99 

Number of bytes in this block 
(reserved) 

(reserved) 

(reserved) 

(reserved) 

(reserved ) 

(reserved ) 


Contents are currently ignored by loaders and system programs for all 


fields. 


Future plans: 


See the VERSION CONTROL - SPECIFICATION document for detailed plans 
for releases 11.0 and 12.0. 
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4.2 MODULE BLOCKS 


ModuleName: 
iModuleName=record 
ModuleName, 
SegmentName: NameString; 
CSize: LongInt; 
(* Comments *) 
end; 


tt tt tt tt ttt ttt ttt nn at 


| 80 | size | ModuleName | SegmentName | CSize | Comments ... | 
at att ttt tt tt ttt tt ttt nat 
1 2 4 5 12 13 20 21 24 size : 
80 - Hexadecimal 80 
size - Number of bytes in this block 


ModuleName - Blank padded ASCII name of this module 
SegmentName - ASCII name of segment in which this module will reside 
Notes: 
CSize is always zero. The actual CSize is in the EndBlock. 
Comments are not currently generated. 
Future plans: 
CSize will be dropped. 
Comments will be replaced with stack frame descriptor for debugging. 


Linker will do language checking and size checking of args and locals. 


EndBlock: 
iEndBlock=record 
CSize: LongInt; 
end; 


teen tae ttt tet 

| 81 | size | CSize | 

fener te ttt 
1 2 4 5 8 


81 - Hexadecimal 81 

size - Number of bytes in this block (always 000008) 

CSize - Numer of bytes in the code block for this module 
Note: 


CSize is the actual number of bytes of code in the CodeBlock, i.e. CSize 


is equal to the number of Variant bytes in the CodeBlock. By convention, the 
Monitor and 0.S. loaders load the CodeBlock header and invariant part as 


well. So other records such as SegLocation blocks and the segment table in 
the Executable block generally indicate a code block size which is larger. 
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EntryPoint: 
iEntryPoint=record 
LinkNane, 
UserName: NameString; 
Loc: SegAddr; 
(* Comments *) 
end; 


tt tt tt ttt tet tet tet tet tte ttt nt 


| 82 | size | LinkName | UserName | Loc | Comments... | 
ene teat ttt ttt ttt tt tt tt tt tit ttt ttn 
1 2 4 5 12 13 20 21 24 25 size 
82 - Hexadecimal 82 
size - Number of bytes in this block 


LinkName - Blank padded ASCII linker name of entry point 
UserName - Blank padded ASCII user name of entry point 
Loc - Location of entry point relative to this module 
Note: 
Comments are not currently generated. 
In Pascal files each module has only one EntryPoint and Loc is zero. 
In Assembly language files there is an EntryPoint record for the .PROC or 


eFUNC and one for each .DEF 
In Intrinsic library files with Linker information there is an EntryPoint 


record for each procedure or function in an Interface section. 


For languages with nested scopes (such as Pascal) LinkName has a special 
format ("Snnnnnnn") for nested names or names in Implementation sections which 


do not need to be unique globally. LinkNames must be unique within a file. 


The Linker will remap the LinkNames to preserve uniqueness when reading the 
file. See Appendix C on the IULinker functions for more details. 


Future plans: 
Addition of UnitName to support qualified name references. 


Switch from eight character case-insensitive names to longer 


case-sensitive names. The length will probably be either a fixed 16 
characters or a varying 31 characters (i.e. an index in a NameTable). 
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External: 
iExternal=record 
LinkName, 
UserName: NameString; 
(* RefVariant *) 
end; 


te ttt ttt ttt tt tt 


|} 83 | size | LinkName | UserName | ref 1]... | ref n | 
tt ttt tt tt nt tet tt 
1 2 4 5 12 13 20 21 24 size 
83 - Hexadecimal 83 


size Number of bytes in this block 
LinkName - Blank padded ASCII linker name of external reference 
UserName - Blank padded ASCII user name of external reference 


ref l ~- Location of first reference relative to this block 
eee - Other references 
ref n - Location of last reference 

Note: 


See the notes and futures plans for names under EntryPoint. 


StartAddress: 
iStartAddress=record 
Start: SegAddr; 
GSize: LongInt; 
(* Comments *) 


end; 

spe tte tt tet ttt ttt ttt ene —+ 

| 84 | size | Start | GSize | Comments ... | 

spe fete tte tte te tet tte ene ne —+ 

1 2 4 5 8 9 12 13 size 

84 - Hexadecimal 84 
size - Number of bytes in this block 
Start - Starting address relative to this block 
GSize - Number of bytes in the global data area 


Comments - Arbitrary information. Ignored by the Linker. 
Note: 
Comments are not currently generated. 
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CodeBlock: 
iCodeBlock=record 
Addr: SegAddr; 
(* ObjectCode *) 
end; 


a ee ee Seer ee Oe ee ee et ee eS 
| 85 | size | Addr | ObjectCode ... | 
pom et tttttttttt nt 


1 2 4 5 8 9 size 
85 ~ Hexadecimal 85 
size - Number of bytes in this block 
Addr - Address of first byte of code 


ObjectCode - The object code. Always an even number of bytes. 


Note: 
For raw object files (unlinked) the address is always 0. 
For linked files the address is an absolute address in the logical 


address space. (MMU # times 128 K + const). 


Relocation: 
1Relocation=record 


(* RefVariant *) 
end; 


iRefVariant=SegAddr; 


tat ttt tn tt ttt 


| 86 | size | ref 1 |... | ref n | 
a a 
1 2 4 5 8 size 
86 - Hexadecimal &6 
size - Number of bytes in this block 
ref l - Location of first address to relocate 


- Other addresses 
Location of last address to relocate 


ref n 
Note: 
Relocation records are generated by the old Linker (partial links) and 
by the old Library program. They are not supported by the current Linker. 
Future plans: 
Reloction records will be used by the PreLink and InstallLink versions 
of the Linker. 
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CommonReloc: 
iCommonRelocation=record 
CommonName: NameString; 


(* RefVariant *) 
end; 


iRefVariant=SegAddr; 


eee ee One ee Se Sr SS er SS SO ee Se Oe St 
| 87 | size | CommonName | ref l |... | ref n | 


tenn atte ttt tt att tt tt ttt ne 
1 2 45 12 13 16 size 


87 - Hexadecimal 87 
size - Number of bytes in this block 
CommonName =- Blank padded ASCII name of common block 


ref l - Location of first reference relative to this module 
eee - Other references 
ref n - Location of last reference 

Note: 


Common relocation references in the code are zero based relative to 
the beginning of the named regular unit. 


ShortExternal: 
iShortExternal=record 


LinkNane, 
UserName: NameString; 
(* ShortRef *) 

end; 


iShortRef=Integer; 


ett tte ttt tt ttt ttt tet tate te ate nna tentent 


{ 89 | size | LinkName | UserName | refl] ... | refn| 
aman ban p= bata te bap hata ttt tet te tt 
1 2 4 5 12 13 — 20 21 22 size 
89 - Hexadecimal 89 
size - Number of bytes in this block (always 000016) 


LinkName - Blank padded ASCII linker name of external reference 
UserName =- Blank padded ASCII user name of external reference 


refl - Location of first address to relocate 
wax - Other addresses 
refn - Location of last address to relocate 
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4.3 UNIT BLOCKS 


UnitBlock: 


iUnitBlock=record 

UnitName: NameString; 

CodeAddr, 

TextAddr: FileAddr; 

TextSize, 

GlobalSize: LongInt; 

UnitType: integer; (* O=Reg, 1l=Intrin, 2=Shared *) 

(* comments = interface section of Unit (compressed) *) 
end; 


A = = ae 


| 92 | size | UnitName | CodeAddr | TextAddr | TextSize |... 
tenant ttt tet et ttt te te te te te te te tate te eteete ne 
1 2 45 12 13 16 17 20 21 24 
a ee ee ee ae eee oe ee —+ 
-..| GlobalSize| UnitType| Comments ... | 
Se ts —+ 
25 28 29 30 31 size 
92 - Hexadecimal 92 
size ~- Number of bytes in this block (always OOO01E) 
Unit Name - Name of this unit 
CodeAddr - Disk address of module 
TextAddr ~- Disk address of text block 
TextSize - Size of text block 
GlobalSize = Number of bytes of globals in this unit 
UnitType ~- O=Regular, 1l=Intrinsic, 2=Shared 
Comments - Compressed ASCII text of Interface 
Note: 
In an unlinked (raw) file: 
CodeAddr is the address of the first Module Name Block (i.e. the 
first byte after this UnitBlock). 
TextAddr is the (block aligned) File Address of the Interface 
(past the EOFMark). 
TextSize is the size of the interface ( = n*1024) where n is the 


number of text pages. 
Comments is missing. | 
The Interface is found in standard .TEXT file blocks. 


In a linked (intrinsic library) file: 


CodeAddr is 0. 
TextAddr is 0. 


TextSi 


ze is 0. 


Comments is either empty (no interfaces in the library) or contains 


the compressed interface (blanks and meaningless comments removed). 


For Pascal the Interface is defined to begin with the character after the 
semicolon in the "Unit Foo;" statement and extends through the word 
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“implementation”. 


Future Plans: 

The kludge of having Text blocks at the end of the file may not be 
supported forever. Compilers should be designed to get interfaces from the 
variant part of the UnitBlock record, whether they are stored in text form or 
are represented as intermediate code. 


InterfLoc: 
iInterfLoc= record 
(* IntfLocVariant *) 


end; 


nant tt tt tnt tt tt 


| 86 | size | loc 1 |... | locn | 
se ptt tp ttt te nn tet te tt 
1 2 4 5 8 size 
92 - Hexadecimal 92 
size - Number of bytes in this block 
loc 1 - Location record for first unit interface 
wae - Other location records 
loc n - Location record for last unit interface 
Note: 


The interface location block is only present if the +I option has been 
specified to the Linker to include interfaces when linking an intrinsic 
library file. 


IntfLocVariant: 
iIntfLocVariant = record 


UnitName: NameString; 
IfLoc: FileAddr; 


end; 


ttt tat tt tet tt 


| wUnitName | IfLoc | 
ttt ttt tt tt 
1 8 9 12 
UnitName - Blank padded ASCII Unit Name 
IfLoc - File Address of first byte of Interface 
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4.4 MAIN PROGRAM 


Executable: 
iExe 
JT 
JT 
Da 
JT 


cutable=record 
Laddr: MemAddr; 


Size, 
taSize, MainSize, 
SegDelta, StkSegDelta, 


DynStack, MaxStack, 
MinHeap, MaxHeap: LongInt; 


(* 


end; 


Unknown = numSegs + JTSegVariants + 
numDescriptors + JumpTVariants + other stuff *) 


ttt tt tt tt ttt te tte tt ttt et tt ttt tt 
| 98| size|JTLaddr| JTSize| DataSize | MainSize | 
JTSegDelta|StkSegDelta|.. 

pc maa aaa tan ttn tte ate te tte te ete te te te tbe te tee te tet - 


1 2 45 


8 9 12 13 16 17 20 21 24 25 28 


tet tte tet ate te a tate te te tet nant 


«eel DynStack 


| MaxStack | MinHeap | MaxHeap | jump table ... | 


a ttt te te tate teat tt te te te tn nnn 


29 32 
98 - 
size = 
JTLaddr - 


JTsize - 
DataSize = 
MainSize - 
JTSegDelta - 


StkSegDelta - 
DynStack - 


MaxStack - 
MinHeap = 
MaxHeap - 
jump table - 


33 36 37 40 41 44 45 size 


Hexadecimal 98 

Number of bytes in this block 

Absolute load address of jump table 

Number of bytes in jump table 

Total number of bytes in regular units global data areas 
Size of main program global data area 

Distance from base of segment to beginning of data pointers 
Distance from JTSegDelta to A5 at runtime 

Initial dynamic stack size 

Maximum total stack size 

Initial heap size 

Maximum total heap size 

The jump table itself. 
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The format of the jump table is: 


eae nnn rm + 
| Number of segments | 2 bytes 


| Main Segment Table | 12 bytes 


| Segment Table #2 | 12 bytes 


Note: 
By convention, the main segment has a blank name, and is the first 
segment in the jump table. Also, the first descriptor in the first segment is 
the entry point for the main program. 
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Segment Table Entry: 
iJTSegVariant = record 
SegmentAddr: FileAddr; 
SizePacked: integer; 
SizeUnpacked: integer; 
MemLoc: MemAddr; 


end; 


ean tn pn pn an nnn nn natn tent tt 


| SegmentAddr | SizePacked| SizeUnpacked| MemLoc | 
tan pane tn nn tn nat nn rn pete nate tent 

1 45 67 8 9 12 
SegmentAddr - File address of either CodeBlock or PackedCode block 
SizePacked - Number of bytes in PackedCode record 
SizeUnpacked - Number of bytes in (unpacked) Code record 
MemLoc - Absolute logical address of segment 


Note: 
If SizePacked = 0 then segment is not packed. 
SizePacked and SizeUnpacked include the invariant part of the record. 
Future plans: 
Both SizePacked and SizeUnpacked will become LongInts at the next 
non-compatible object code release. 


Jump Table Descriptor: 


iJumpTVariant = record 
JumpL: integer; 
AbsAddr: MemAddr; 


end; 


feet tet ttt 
| JumpL | AbsAddr_ | 

pen apen teat ttt 
1 2 3 6 


JumpL - JMP.L $xxxxxxx instruction 
AbsAddr - Absolute address of procedure in logical address space 
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4.5 INTRINSIC UNITS 


SegmentTable: 
iSegmentTable = record 


nSegments: integer; 
(* SegVariant *) 


end; 
enna ttt +--+ -- - +--+ ------- +- 9 -+--------- + 
| 94 | size | nSegments | segInfol | ... | segInfoN | 
A oo —+-  —--------- —+ 
1 2 45 7 25 size 
9A ~ Hexadecimal 9A 
size - Number of bytes in this block 


nSegments - Number of segment descriptors in table 
segiInfol ~ First SegVariant record 
segIinfoN - Last SegVariant record 

Note: 

The Segment Table contains the transitive closure of the intrinsic 
segments referenced by segments in this file. The transitive closure is 
currently computed fairly loosely: inclusion of a file in the Linker input 
list is taken as a reference to all the segments in the file. This is 
consistent with the notion of “reuseable” and the notion of “changes in 
implementation" not affecting reuseability, i.e. references can be added to 
other parts of a lower level library without affecting the transitive closure 
computation. 


iSegVariant = record 
SegName: NameString; 
SegNumber: integer; 
Versionl: longint; 
Version2: longint; 
end; 


tt tata tt nat nt tat tat tate att 


| SegName |SegNumber| Versionl | Version2 | 
ttt tat ten nnn enn tte tte atten te tte ate te tat 
1 9 1l 15 18 
SegName ~- Segment Name . 
SegNumber - Segment (MMU) number 
Versionl - (reserved) 
Version2 - (reserved) 
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UnitTable: ; 
iUnitTable = record 
nUnits, 
maxunit: integer; 
(* UnitVariant *) 
end; 
ttt nat nn en eee t-te ----- = —+ 
| 9B | size | nUnits| maxunit |UnitInfol | ... |UnitInfon | 
tenn ttt tt tt +- 9 -+-------- —+ 
1 2 45 7 9 21 size 
9B - Hexadecimal 9B 
size ~ Number of bytes in unit table block 
nUnits - Number of unit descriptors in table. 


maxunit - maximum unit number found in the table. 
UnitInfol First UnitVariant record 


UnitInfoN - Last UnitVariant record 


Example: 
If units number 1, 7, and 11 are present then nUnits=3 and 


maxunit=1l. 


iUnitVariant = record 
UnitName: NameString; 
UnitNumber: integer; 
UnitType: integer; 
end; 


Sy ee eae ar et a eer et Gmc nenoee Uneneey enero Ss 
| UnitName | UnitNumber! UnitType| 

fetta ttt ttt nat nnn tnt t 
1 9 10 11 12 


UnitName - Unit Name 
UnitNumber ~ Index into data pointer table 
UnitType ~ O=Regular, l=Intrinsic, 2=Shared 


Note: 
UnitType = 0 would be an error. 
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SegLocation: 
iSegLocation = record 
nSegments: integer; 
(* SegLocVariant *) 


end; 
fern poet nant a een + 
| 9c | size  |nSegments| segInfol | ... | segInfoN | 
penne ttt t= = oT oeeenenie + 
1 2 45 67 size 


9C Hexadecimal 9C 

size - Number of bytes in segLocation block 
nSegments - Number of segment descriptors in table. 
segiInfol - First SegLocVariant record 


segInfoN - Last SegLocVariant record 


iSegLocVariant = record 
SegName: NameString; 
SegNumber: integer; 
Versionl, Version2: longint; 
FileNumber: integer; 
FileLocation: FileAddr; 
SizePacked, SizeUnpacked: integer; 
end; 


tat ttt na nat te atte teat att t= 


| SegName |SegNumber| Versionl | Version2 |.... 
se a et ee et rs ee ee ee Se Se ee 
1 9 ll 15 18 


ee ee Cee eee Sa a Se Oe Sn ECE SE 
.e- | FileNumber] FileLocation | SizePacked| SizeUnpacked | 
eccrine nna poem pea pena aa een ape peer a panna a} 


19 20 21 24 25 26 27 28 
SegName - Segment Name 
SegNumber - MMU number 
Versionl - (reserved ) 
Version2 - (reserved) 


FileNumber - Index into the FilesBlock file table 
FileLocation - Location within file of CodeBlock 
SizePacked <- Number of bytes in PackedCode record 


SizeUnpacked - Number of bytes in (unpacked) Code record 


Note: 
If SizePacked = 0 then Segment is not packed. 


FileLocation may become invalid when variations are allowed in 


an intrinsic unit or main program file. 
SizePacked and SizeUnpacked will become longints. 
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UnitLocation: 
iUnitLocation = record 
nUnits: integer; 
(* UnitLVariant *) 


end; 
Se ee t-te ------ + 
| 9D | size | nUnits|UnitInfol | ... |UnitInfoN | 
tema te ape eaten ten ape nee neenn —+- 9 -+--------- —+ 
1 2 45 7 23 size 
9D - Hexadecimal 9D 
size - Number of bytes in unitLocation block 


nUnits - Number of unit descriptors in table. 
UnitInfol - First UnitLVariant record 


Unit InfoN Last UnitLVariant record 


iUnitLVariant = record 
UnitName: NameString; 
UnitNumber: integer; 
FileNumber, UnitType: FileByte; 
DataSize: longint; 


end; 

het tetate te teteten nna open ttt 
| UnitName | UnitNumber|FileNumber|UnitType| DataSize | 

ur rl it ote Wier Wee wr Yuna WASNIa Or HONING NY aPC t+ -+- +--+ 
1 9 10 11 12 13 16 
Unit Name - Unit Name 


UnitNumber - Index into data pointer table 
FileNumber - Index into the FilesBlock file table 


UnitType - See UnitTable above 
DataSize - Size in bytes of global data area for unit 
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FilesBlock: 
iFilesBlock = record 
nFiles: integer; 
(* Unknown = FilesVariant + string table *) 


end; 
t-te tt ttt ttt ttt ttt tt —+ 
| 9E | Size | nFiles | FileInfol | ... | FileInfoN | StringTable ... | 
spe ee tenn tet tate tate ae be tte t tet] teen ne nnn n ene ne -+ 
1 2 4 5 6 7 13 size 
9E - Hexadecimal 9E 
nFiles - number of file descriptors in block. Each Fileinfo record 
FileInfol - First FilesVariant record 
FileInfoN - Last FilesVariant record 
iFilesVariant = record 
FileNumber: integer; 
NameAddr: FileAddr; 
end; 
er fp nn pe tte tent 
| FileNumber| NameAddr | 
qe nn tt te tet 
1 2 3 6 
FileNumber - Index into the FilesBlock file table 
NameAddr - File address of name string 
Note: 


Each StringTable entry has the format of a Pascal string, i.e. the 
strings begins on an even byte and the first byte is a length byte indicating 
how the length of the string. 


4.6 CODE COMPACTION 


PackedCode: 
iPackedCode = record 


addr: MemAddr; 
csize: longint; 
(* Unknown = packed object code *) 


end; 


addr - Absolute address in logical address space 
csize - Size in bytes of the code when unpacked 
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PackTable: 
iPackTable = record 
packversion: longint; 
(* Unknown = translation table *) 
end; 
Note: 


The packversion field was originally intended to indicate changes in 
the packing algorithm. With the 0.S. supporting one PackTable for the systen, 
packversion could also be used to indicate which table. 


EOFMark: 
pepe pepe t 
100} 000004 | 
tho ttt 
LQ 4 


The EOFMark block marks the end of an object file (almost). 


Note: 
Text blocks can occur past the EOFMark. 


References 


[1] Niklaus Wirth, “MODULA-2", Institut fur Informatik der ETH, 1980. 
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Appendix A. ObjIOLib Interface 


(RRRRERKERERRKRE ERE EER ERE REE RRR ERE REE RERER EERE RERE RRR EKER REKRERERERERERREEEKKE ) 


(* *) 
(* File: LIB:OBJIO ~ *) 
Gu *) 
(* (C) Copyright 1981, 1982 *) 
(* Apple Computer, Inc. *) 
* *) 
(* 9-Jul-82 *) 


(RRRKEREKRERERERRERERERERERERERERERERERERKEREREREREREEREREREEERERERRERERERERKKE ) 
{$S LIB1 } 


unit ObjI0; 
intrinsic; 


(* ObjIO is a unit defining and providing blockwise and bytewise read/ *) 
(* write access to object-format files. All I/O goes through FilelI0O. *) 


interface 
uses 
(*SU PASDEFS.OBJ *) PasDefs, 
(*SU UTILITY.OBJ *) Utility, 
(*$U FILEIO.OBJ *) Filel0; 


(* Note: distinctions -- *) 

(* OldExecutable (old compilers, either machine) *) 

(* PhysicalExec (New compiler, old linker, either machine, physical) *) 
(* Executabe (New compiler, either linker, new machine, logical) *) 


(* New linker links Intrinsic Units and produces a version control record. *) 


type 
"BlockType=(ModuleName, EndBlock, EntryPoint, 
External, StartAddress, CodeBlock, 
Relocation, CommonReloc, CommonDef, 
ShortExternal, QuickLoad, OldExecutable, 
LibModule, LibEntry, UnitBlock, InterfLoc, 
PhysicalExec, Executable, VersionCtrl, 
SegmentTable, UnitTable, SegLocation, UnitLocation, FilesBlock, 
PackedCode, PackTable, DebugSymbols, 
DebugEntry, DebugCommon, EOFMark, UnknownBlock); 


VariantType=(NoVariant, (* must be first *) 
RefVariant, ShortRef, ModVariant, Comments, 
SegVariant, UnitVariant, IntfLocVariant, 
SegLocVariant, UnitLocVariant, FilesVariant, 
JumpTVariant, JTSegVariant, ObjectCode, ProcHeap, 
OldJumpTV, OldJTSegV, 

(* must be last *) UnknownVariant); 


FileAddr = longint; (* 0 based, byte address within a file *) 


August 14, 1982 aaa) OS 5.2 Monitor 10 


Lisa Object File Formats 


MemAddr = longint; (* 24-bit virtual address *) 


SegAddr = longint; (* 0 based, byte address within a segment *) 


(* Variant Definitions *) 
iRefVariant=SegAddr ; 
iShortRef=Integer; 
iModVariant=Integer ; 


iSegVariant = record 
SegName: NameString; 
SegNumber: integer; 
Versionl: longint; 
Version2: longint; 
end; 


iUnitVariant = record 
UnitName: NameString; 
UnitNumber: integer; 
UnitType: integer; 
end; 


iIntfLocVariant = record 
UnitName: NameString; 
IfLoc: FileAddr; 


end; 


iSegLocVariant = record 

SegName: NameString; 

SegNumber: integer; 

Versionl: longint; 

Version2: longint; 

FileNumber: integer; 

FileLocation: FileAddr; 

SizePacked: integer; (* size of PackedCode record *) 

SizeUnpacked: integer; (* size of CodeBlock record *) 
end; 


iUnitLVariant = record 
UnitName: NameString; 
UnitNumber: integer; 
FileNumber, UnitType: FileByte; 
DataSize: longint; 

end; 


iFilesVariant = record 
FileNumber: integer; 


NameAddr: FileAddr; 
(* one per file, followed by string table *) 


end; 


iJumpTVariant = record 
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JumpL: integer; 
AbsAddr: MemAddr; 
end; 


1OldJumpTV = record 
RelOffset: longint; 


Noop: integer; (* not in Memory = JMP.L *) 
Jump: integer; (* not in Memory = Adrress of %ZLOADIT *) 
PCRel: integer; 

end; 


i0ldJTSegV = record 
Addrl: MemAddr; (* Address of First Proc Descriptor *) 
FileLoc: FileAddr; 
CodeSize: longint; 
MemLoc: MemAddr; 
RetAddr: MemAddr; 
RefCount: longint; 
ActiveList: MemAddr; (* -l = End Of List ?? *) 
Reserved: longint; 
end; 


iJTSegVariant = record 


SegmentAddr: FileAddr; (* points to CodeBlock or PackedCode *) 
SizePacked: integer; (* size of PackedCode record *) 
SizeUnpacked: integer; (* size of CodeBlock record *) 
MemLoc: MemAddr; (* Logical Addr *) 

end; 


(* Invariant Definitions: *) 


iModuleName=record 
ModuleName, 
SegmentName: NameString; 
CSize: LongInt; 
(* Comments *) 

end; 


1EndBlock=record 
CSize: LongInt; 
end; 


iEntryPoint=record 
LinkNane, 
UserName: NameString; 
Loc: SegAddr; 
(* Comments *) 

end; 


1External=record 


LinkNane, 
UserName: NameString; 


August 14, 1982 - 33 - OS 5.2 Monitor 10 


Lisa Object File Formats 


(* RefVariant *) 
end; 


iStartAddress=record 


Start: SegAddr; 
GSize: LongInt; 


(* Comments *) 
end; 


iCodeBlock=record 
Addr: SegAddr; 
(* ObjectCode *) 
end; 


iRelocation=record 
(* RefVariant *) 
end; 


iCommonRelocation=record 


CommonName: NameString; 
(* RefVariant *) 


end; 


iCommonDefinition=record 
CommonName: NameString; 
DSize: LongInt; 
(* Comments *) 

end; 


iShortExternal=record 
LinkNanme, 


UserName: NameString; 
(* ShortRef *) 
end; 


iQuickLoad=record 
StartLoc: SegAddr; 
DataSize: LongInt; 
(* ObjectCode *) 
end; 


iLibModule=record 
ModuleName: NameString; 
ModSize: LongInt; 
CodeAddr, 
TextAddr: FileAddr; 
TextSize: LongInt; 
NrMods: Integer; 
(* ModVariant *) 

end; 


iLibEntry=record 


LinkName: NameString; 
Module: Integer; 
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Address: SegAddr; 
end; 


iUnitBlock=record 

UnitName: NameString; 

CodeAddr, 

TextAddr: FileAddr; 

TextSize, 

GlobalSize: LongInt; 

UnitType: integer; (* O=Reg, 1=Intrin, 2=Shared *) 

(* comments = interface section of Unit (compressed) *) 
end; 


iInterfLoc= record 
(* IntfLocVariant *) 


end; 

iExecutable=record 
JTLaddr: MemAddr; 
JTSize, 
DataSize, (* Global Area, Reg Units *) 
MainSize, (* Global Area, Main Program *) 
JTSegDelta, (* Jump Table Segment Delta *) 
StkSegDelta, (* Stack Segment Delta *) 
DynStack, (* Initial Dynamic Stack Size *) 
MaxStack, (* Max. Total Stack Size *) 
MinHeap, (* Initial Heap Size *) 
MaxHeap: LongInt; (* Max. Total Heap Size *) 


(* Unknown = numSegs + JTSegVariants + 
numDescriptors + JumpTVariants + other stuff *) 


end; 


10ldExecutable=record 
JTLaddr: MemAddr; 


JTSize, 

DataSize: LongInt; (* Global Area, Reg Units *) 

(* Unknown = numSegs + OldJTSegVs + OldJumpTVs + other stuff *) 
end; 


iPhysicalExec#record 
JTLaddr: MemAddr; 


JTSize, 

DataSize, (* Global Area, Reg Units *) 
MainSize, (* Global Area, Main Program *) 
JTSegDelta, (* Jump Table Segment Delta *) 


StkSegDelta: LongInt; (* Stack Segment Delta *) 
(* Unknown = numSegs + OldJTSegVs + 
DummyPtr + OldJumpTVs + other stuff *) 
end; 


iVersionCtrl = record 
sysNun, minSys, 
maxSys, Reservl, 
Reserv2, Reserv3: longint; 
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end; 


iSegmentTable = record 
nSegments: integer; 
(* SegVariant *) 
end; 


iUnitTable = record 
nUnits, 
maxunit: integer; 
(* UnitVariant *) 
end; 


iSegLocation = record 
nSegments: integer; 
(* SegLocVariant *) 
end; 


iUnitLocation = record 
nUnits: integer; 
(* UnitLVariant *) 
end; 


iFilesBlock = record 

nFiles: integer; 

(* Unknown = FilesVariant + string table *) 
end; 


iPackedCode = record 

addr: MemAddr; 

csize: longint; 

(* Unknown = packed object code *) 
end; 


iPackTable = record 
packversion: longint; 
(* Unknown = translation table *) 


end; 


iDebugSymbols=record 
UserName, 
SegName: NameString; 
ProcBase, 
ProcSyns, 
ProcStnt, 
ProcNode, 
UsesSize: LongInt; 
{ if UsesSize<>0 then ... these have valid values: } 
HoleBase, 
HoleTop, 
MapBase, 
MapTop: LongInt; 
MapName: NameString; 
{ later } 
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(* ProcHeap *) 
end; 


iDebugEntry=record 
UserName: NameString; 
EntrySeg: Longint; 
EntryLoc: SegAddr; 
(* Comments *) 

end; 


iDebugCommon=record 
UnitName: NameString; 
CommonBase: MemAddr; 
(* Comments *) 

end; 


1Unknown=record 
(* UnknownVariant *) 


end; 


ObjBlock=record 
Variant: VariantType; 
NrVariants: LongInt; 
case BlockHeader: BlockType of 


ModuleName: (bModuleName: 
EndBlock: (bEndBlock: 
EntryPoint: (bEntryPoint: 
External: (bExternal: 
StartAddress: (bStartAddress: 
CodeBlock: (bCodeBlock: 
Relocation: (bRelocation: 
CommonReloc: (bCommonReloc: 
CommonDef : (bCommonDef: 
ShortExternal: (bShortExternal: 
QuickLoad: (bQuickLoad: 
OldExecutable: (bOldExecutable: 
LibModule: (bLibModule: 
LibEntry: (bLibEntry: 
UnitBlock: (bUnit Block: 
InterfLoc: (bInterfLoc: 
PhysicalExec: (bPhysicalExec: 
Executable: (bExecutable: 
VersionCtrl: (bVersionCtrl: 
SegmentTable: (bSegmentTable: 
UnitTable: (bUnitTable: 
SegLocation: (bSegLocation: 
UnitLocation: (bUnitLocation: 
FilesBlock: (bFilesBlock: 
PackedCode: (bPackedCode: 
PackTable: (bPackTable: 
DebugSymbols: (bDebugSymbols: 
DebugEntry: (bDebugEntry: 
DebugCommon: (bDebugCommon: 
UnknownBlock: (bUnknown: 
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iModuleName) ; 
iEndBlock); 
iEntryPoint); 
iExternal); 
iStartAddress); 
iCodeBlock); 
iRelocation); 
iCommonReloc); 
iCommonDef ); 
iShortExternal); 
iQuickLoad) ; 
10ldExecutable); 
iLibModule); 
iLibEntry); 
iUnitBlock); 
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iPhysicalExec); 
iExecutable); 
iVersionCtrl); 
iSegmentTable); 
iUnitTable); 
iSegLocation); 
iUnitLocation);. 
iFilesBlock); 
iPackedCode); 
iPackTable); 
iDebugSymbols); 
iDebugEntry) ; 
iDebugCommon) ; 
iUnknownBlock); 
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end; 


ObjVarBlock = record 


case VarHeader: VariantType of 


RefVariant: (bRefVariant: iRefVariant); 
ShortRef: (bShortRef: iShortRef); 
ModVariant: (bModVariant: iModVariant); 
SegVariant: (bSegVariant: iSegVariant); 
UnitVariant: (bUnitVariant: iUnitVariant); 
IntfLocVariant: (bIntfLocVariant: iIntfLocVariant); 
SegLocVariant: (bSegLocVariant: iSegLocVariant); 
UnitLocVariant: (bUnitLVariant: iUnitLVariant); 
FilesVariant: (bFilesVariant: iFilesVariant); 
OldJumpTV: (bOldJumpTV: i0ldJumpTV) ; 
OldJTSegV: (bO1ldJTSegV: 101ldJTSegV) ; 
JumpTVariant: (bJumpTVariant: iJumpTVariant) ; 
JTSegVariant: (bJTSegVariant: iJTSegVariant) 

end; 

Ob jHandle=*ObjDesc; 

Ob jDesc=record 


ObjFile: FileHandle; 
NextBlock: FileAddr; 
end; 


procedure InitObjFile (var ObjPtr: ObjHandle; nBlocks: integer); 
(* InitObjFile initializes ObjPtr and allocates a buffer of nBlocks *) 


procedure OpenObjFile (var ObjPtr: ObjHandle; FileName: LString; 
NewFile: Boolean); 
(* OpenObjFile initializes ObjPtr to the file FileName. The file is *) 
(* scratched if NewFile is set. *) 


procedure ZeroObjEnd (ObjPtr: ObjHandle); 
(* Zero ObjEnd fills out the current block with zeroes *) 


procedure CloseObjFile (ObjPtr: ObjHandle; Save: Boolean); 
(* CloseObjFile closes an object file. If Save is set then the file is *) 
(* locked. Otherwise, the file is left in the state it was in before *) 
(* it was opened. *) 


procedure GetObjPtr (ObjPtr: ObjHandle; var BytePtr: FileAddr); 
(* GetObjPtr returns the position of ObjPtr’s “read/write head". *) 


procedure GetObjBlockPtr (ObjPtr: ObjHandle; var BytePtr: FileAddr); 
(* sets BytePtr to the file location of the next ObjBlock to be read *) 


procedure SetObjPtr (ObjPtr: ObjHandle; BytePtr: FileAddr); 
(* SetObjPtr positions the “read/write head" BytePtr bytes from the *) 
(* beginning of ObjPtr. The invariant access flow is not altered, *) 
(* that is to say the next (Get/Put)ObjInvar accesses the sequentially *) 
(* next invariant following the variant that we°re in before calling *) 
(* SetObjPtr. *) 
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procedure SetObjBlockPtr (ObjPtr: ObjHandle; BytePtr: FileAddr); 
(* SetObjBlockPtr positions the "read/write head" BytePtr bytes from *) 
(* the beginning of ObjPtr. BytePtr must point to the beginning of an *) 
(* invariant. That invariant will be accessed with the next *) 
(* (Get/Put)ObjInvar. *) 


procedure SkipObjBytes (ObjPtr: ObjHandle; NrBytes: LongInt); 
(* SkipObjBytes moves the file pointer of file ObjPtr NrBytes bytes. *) 


procedure SetObjInvar (var B: ObjBlock; InvarType: BlockType; 


VarSize: LongInt); 
(* SetObjInvar sets some fields in B. B is of InvarType type with *) 


(* VarSize bytes in its variant. *) 


procedure CopyObjSeq (InObj, OutObj: ObjHandle; NrBytes: Integer); 
(* CopyObjSeq copies a sequence of NrBytes bytes from InObj to OutObj. *) 


procedure GetObjInvar (ObjPtr: ObjHandle; var Stuff: ObjBlock); 
(* GetObjInvar reads the invariant part of an object block. *) 
(* The user can read the variant part, if so desired. *) 


procedure GetObjVar (ObjPtr: ObjHandle; VarType: VariantType; 
var Stuff: ObjVarBlock); 
(* GetObjVar reads a variant part of the specified type *) 


(* into the ObjVarBlock *) 


procedure GetObjName (ObjPtr: ObjHandle; var N: NameString); 
(* GetObjName reads a name from file ObjPtr. *) 


procedure GetObjSeq (ObjPtr: ObjHandle; Stuff: Ptr; NrBytes: Integer); 
(* GetObjSeq moves NrBytes bytes from ObjPtr to the area pointed to by *) 
(* Stuff. *) 


procedure GetObjByte (ObjPtr: ObjHandle; var B: Byte); 
(* GetObjByte reads a byte from file ObjPtr. *) 


procedure GetObWord (ObjPtr: ObjHandle; var W: Integer); 
(* GetObWord reads an integer from file ObjPtr. *) 


procedure GetObjLong (ObjPtr: ObjHandle; var L: LongInt); 
(* GetObjLong reads a longint from file ObjPtr. *) 


procedure PutObjInvar (ObjPtr: ObjHandle; var Stuff: ObjBlock); 
(* PutObjInvar writes the invariant part of an object block. *) 


procedure PutObjVar (ObjPtr: ObjHandle; VarType: VariantType; 
var Stuff: ObjVarBlock); 
(* PutObjVar writes a variant part of the specified type *) 
(* from the ObjVarBlock *) 


procedure PutObjName (ObjPtr: ObjHandle; N: NameString); 
(* PutObjName writes a name to file ObjPtr. *) 


procedure PutObjSeq (ObjPtr: ObjHandle; Stuff: Ptr; NrBytes: Integer); 
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(* PutObjSeq moves NrBytes bytes from the area pointed to by Stuff *) 
(* to ObjPtr. *) 


procedure PutObjByte (ObjPtr: ObjHandle; B: Byte); 
(* PutObjByte writes a byte to file ObjPtr. *) 


procedure PutObWword (ObjPtr: ObjHandle; W: Integer); 
(* PutObford writes an integer to file ObjPtr. *) 


procedure PutObjLong (ObjPtr: ObjHandle; L: LongInt); 
(* PutObjLong writes a longint to file ObjPtr. *) 


implementation 
end. 
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Date: July 17, 1983 
From: Ron Johnston 
Subj: Format of .SYMBOLS files 


The Lisa Assembler can produce a .SYMBQLS file that gives the mapping between 
symbol names and their locations within a code segment. The file format is 
very simple: 


A .SYMBOLS file is a sequence of 12-byte records of the following structure: 
$n + - = + ---------------- + 


' Symbol_Name (8 bytes) 'Location¢4 byte)! 
$ er nn ¢---------------- + 


Symbol Name - left-adjusted, with names shorter than 8 characters padded on 
the right with blanks. They are case shifted, if necessary, to 
be all upper case. 


Location - Gives the byte offset within the module from the beginning of code. 
The symbol] records are alphabetized within the file by Symbol_Name. The file 
is terminated by a record of al!l zeros (@). The remainder, if any, af the fina! 


block is also zeraed, 


I have included a dump of the MONITOR.SYMBOLS file as an example. 
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File: monitor. symbols Block ® 06 


@& ile: monitor. symbols Block 
0 2 4 6 8 A 


MSYMBOLS. TEXT 
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85 ..:.ALRAMH ° 


BLOCK8O . rts ; 


UTB ..?.BSSPBS ° 
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CANTSTX .. 2bCDBU' 
Y ..., CDCLEAR ° 
CDERROR . 
poet rit 


-AD . CORUXIT * 


. 


O2468 ACE. 
. CDOSKCSZ . 


 CDSKINIT. ” sedsic’ 


“,,. PCHKMTBL ... 
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‘DEVNUMS ... rDEVN' 


O2468 ATE 
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oe © © © © we eo ew ew 


‘eaten! era: 


.. FCLOSE1 ..1.° 


O2468 ACE 


eppia computer 
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0010: $752 2020 0000 184C 
0020: 0000 1730 4045 4041 
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2020 2020 
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* FCLOSEX ere Aa 
: 5. FGET1 ‘ 


. 7. FGET2L < 


‘FGET2ND .. 6. FGET 
"3RD . .. 7FGETNOP ° 


;FINDLP me 


FPU ip 
“NOP . _ SXF READCHR’ 


4. FREADLN . . 5(' 


‘ FREEP120. . ". FREE’ 
‘P1124... “°. FREEP136" 
"pap gEREEPIAO.. bee 
* FRESET a, 

“EX. . SFR HEXEC 


O2Z246BACE 
.-GFSEEK ..9.° 


* FSEEK1 . ETCH’ 
‘DIR . ” @IFTCHDRS * 


- ETCHDRY. «fF TCH 
“ERR .. S6FURITELN’ 


. 4, FURTCHAR. . 4. ° 


* FURTCHX .. 4. GET ° 


EO i osh'init 


INITMIX ...xINIT’ 


024 e BACE 


PRG . INITSYS © 


INITSYSF.. 


; INITUTBL. INIT 


eee we 


“XIT . _LINSNTRY ° 


ITS ..; OJERROR ° 
:,? JINDXERR. | R 


TBL ...HLOOPVOL ° 
LPL . E.° 


‘LPL2 sw. E. LL’ 


SH_.. %. MAINLOOP’ 
KRO 
. BMDSKREAD. . . (" 


O246B ACE 


‘MDSKRES . 


. MOSK’ 
oO'UR.. _LHOSKURT 
*... OMEMA 2 


epeple computar 
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4D04S 4D52 4541 4420 
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0000 OBE4 4048 414C 
4D49 4F45 S252 2020 
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0 2 4 6 

5345 5454 $747 5920 
$041 3520 0000 441A 
0000 218A 5346 5843 
S346 S846 4FS4 4F20 
$241 4620 0000 2196 
0000 2190 5346 5854 


8 a 

oooo OED2 
5346 5842 
4F44 4520 
0000 219C 
5346 5849 
4558 5420 


0000 


MDYMBULS. IEAl 


*MEHREAD .... MEMUW 
ree 


: 7.4 ..' 
; NEXTBUF .<. NEXT" 


‘ NONUMBS ... »NOT4' 
*....NOTACR ..K™ 


‘ NOTBACK . _K. NOTD’ 
"ISK .....NOTOKLH ° 


O2468 ACE 
* “NOTPHGR . : 


‘OK 1 <. OPNC’ 
(ODE HOPNEXEC ° 
2 TP. Lo" 


= 
2 
-_— 
~4 
v: 
oO: 
“: 
3° 
oO 


, Sk’ 
Seale .PJMPTBL ° 
a  . a 
*PL2 .E, PMAD’ 
* DR2S. . @\POKEXCP ° 


: PRTELR US RTD: 


‘PUTPRF1 .. ETPUTP’ 


O2468 ACE 
“RF2 .. EFPUTPRFX ' 
*,, E2QUITOSK ....° 
“RCERR- .... RDDA’ 


‘SCNSTRC ... @SEND' 
‘CHD ... pSENDHDR ° 
_XSETALA2 .. °p' 
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apple computer 


ruye ur 
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0060: 534B S053 594E 4320 0000 O4CE $34D 5343 ° SKPSYNC ....SHSC 
0070: 4£46 4F20 0000 060A S34E 4452 3120 2020 ‘'NFO....SNOR1 
0080: O000 1436 S34F 4654 4230 2020 0000 5E32 '.., 6SOFTBO ..>2° 
0090: 5S34F 4654 4250 5420 0000 3E2E S34F 4654 ° SOFTBPT .. >. SOFT’ 
OOAD: 5849 $420 0000 ZEAE 5354 4152 5455 5020 'XIT ..>. STARTUP ° 


0000: 5553 5220 0000 4384 S354 494C 4C49 4E20 "USR ..C. STILLIN ° ’ 
OOEO: O000 30SC $354 5254 4F42 4A20 0000 4AGE ‘, @\STRTOBJ . _ In’ 

OOFO: 5354 5254 $244 2020 0000 14C2 5354 5254 ‘STRTRD . .STRT 

0100: S752 5420 0000 15C8 5355 4D44 4952 2020 ‘ WRT .... SUMDIR 

0110: O000 22FA 5355 4044 4952 4C20 0000 2316 '..”. SUMDIRL .. #.° 

0120: 5355 4044 4952 5820 0000 2320 S357 4150 ° SUMDIRX .. # SWAP’ 

0130: 4AS4 2020 0000 41E6 5359 5350 S24F 4720 ‘JT ..A. SYSPROG ° 

0140: 0000 4D6C 5448 4545 4€44 2020 0000 4F22 ° .MITHEEND. ..0"° 


0150: 544C 504C 2020 2020 0000 448A S44F SO2E TLPL . D. TOP. ° 
0160: 3836 2020 0000 3C16 S44F 5053 5953 4320 ' 86 ae TOPSYSC ° 
0170: O000 0004 S44F 5053 5953 4620 0000 0130 °.. Gieod .. 0 
0180: S44F SOSS 5442 4C20 0000 0032 5450 4C20 ° ToPUTBL , 2TPL.* 
0190: 2020 2020 0000 448C $452 5032 4D41 $820 ° alae gs 
01A0: 0000 4E0C 5452 5032 4043 $320 OO00 4EEB ° _n. TRPOMCS 
01B0: 5452 $943 5256 2020 0000 10DC S452 5944 ‘TRYCRV _TRYD' 


01CO: 4255 4720 0000 4CC6 S452 5945 S845 tenn Oe vay L. sane 


: 1 
O1E£0: $452 S94E 4558 5420 0000 3ADE S452 5S94E “TRYNENT . TRYN' 
01F0: 4A40 S020 0000 OF3SE 5452 5950 4950 2020 ‘JHP . _ > TRYP IP : 


BF ile: monitor. symbols Block #® 10 
0 2 4 6 8 a Cc E€ Q2468 ACE 
0000: 0000 1006 $4S2 S951 2020 2020 0000 4CF4 °....TRYQ ee” 


0040: 5542 $553 5920 2020 0000 1CE6 S543 4CS2 SY uc 
00S0: 2020 2020 0000 1CBC $549 4F20 2020 2020 : 
0060: OOOO 1CCE SS54E 2E4C 4F4F S020 0000 3068 sh 
0070: SS4E 4954 424C 2020 0000 O8AD 5S54E 4954 ‘ UNITBL UNIT 
0080: 4253 5920 0000 1BA2 554E 4954 434C S220 * BSY UNITCLR 
0090: OCOO 1BBE 554E 4954 4445 S620 0000 196A UNIT j 
OOAO: SS4E 4954 4953 4220 0000 221C 5S54E 4041 ° UNITISB ..“. UNMA 
0OBO: S020 2020 0000 226A S550 5348 4654 2020 UPSHF T 


OOFO: 0000 2242 5557 5249 5445 2020 0000 1CCcé ’..” BUUR ITE eee 
: : +? 


0120: 0000 3DEC 5632 3420 2020 2020 0000 3E28 =, V24 >( 

0130: 5633 2020 2020 2020 0000 30F2 5633 3120 ‘Vv: = 

0140: 2020 2020 0000 3DB2 S633 3141 2020 2020 =. V31A 

0150: 0000 3DAE 5633 3158 2020 2020 0000 3DBE =, V31X = 

0160: 5634 2020 2020 2020 0000 3DF8 S635 2020 = 

0170: 2020 2020 0000 3DFE S636 2020 2020 2020 @, V6 

0180: 0000 3£04 S637 2020 2020 2020 0000 3E0A ‘..>. V7 eaten 

0190: $638 2020 2020 2020 0000 3E10 S639 2020 ‘V8 rn: ( 
Q1A0: 2020 2020 0000 3£16 5641 4C49 4442 3720 ° >. VALIDB7 ° 

O1B0: 0000 OEA4 S64F 4C53 S243 4820 0000 256E ve H ..%n 


O1FO: S732 4CSO 4C20 2020 0000 0816 S732 SO4C * W2LPL W2PL. 
Wile: monitor. symbols Block # 11 

0 4 6 8 Cc O2468 ACE 
0000: 2020 2020 0000 0818 $741 4954 2020 2020 , 
0010: 0000 4528 S743 S24C 4620 2020 0000 46C6 E( WCRLF F 


0120: 5445 3320 0000 477C S845 5155 5445 3420 ‘ TE3 .. Gl XEQUTE4 ° 
0130: 0000 475C 5849 S44E 5452 5920 0000 2AG6 ¢ .G\XITNTRY ..°f 


0140: S84C 504C 2020 2020 0000 46FO S850 4C20 ° XLPL .F. XPL 
0150: 2020 2020 0000 46F2 5853 S452 5455 5020 ° ..F.XSTRTUP * 
0160: 0000 0828 S92E 4552 S24F S220 0000 2208 ° RR “ 


: vate tee heed re Nad 
O1A0: SASA 494F S245 S320 0000 1004 SASA 4C4F “ADIT «Zi NCOAD’ 


Using LisaBug 


Ed Birss 


What to do when you crash, hang or loop 


When & program crashes in the Office System, and the release has LisaBug, you 
end up in LisaBug. You can then poke around for a while, but eventually you 
will want to get on to other things. To get out of LiseBug, you need to know 
a few things. The register display, on the right of the third line has a 
piece that says DO=0 (or 1,2,or 3). The DO stands for domain, and if the 
domain is nonzero and it does not say overridden to 0, then to resume you 
should type the LisaBug command G. This is the typical crash found in the 
Office System, and using the G command forces the process into the terminate 
exception handler, and things can be put away neatly. If you are in domain 0, 
or overridden to zero, you should use the OSQUIT command. 


If you are stuck and nothing is happening in response to power offs, key input 
or mouse clicks, you are either looping or are hung. In either case you want 
to hit NMI. If the display is not in domain 0, you are probably looping. Ta 
kill the process, you can type GO, or PC O followed by G. This sets the 
program counter to 0 and tries to access location 0 which is illegal and 
causes a bus error. Typing G after this bus error will terminate the process 
neatly. 


If you are in domain O and you are sitting on an RTS instruction, type id 
PC-4. If the result is a STOP instruction, then you may be hung. You should 
first make sure that you are not doing any I/D. Type G to continue and watch 
the ProFile lights and listen for diskette 1/0. If I/0 is in progress, you 
can wait for the 1/0 to complete, or you can follow instructions on looping 
which follow. If however, no 1/0 is in progress, and when you hit NMI you are 
still on and RTS instruction and the STOP instruction preceed the RTS, type 
QSQUIT to clean up the OS and file structures. 


If you are in domain O and are not on an RTS instruction, you should type G 
and then NMI again. Eventually you should get out of domain O or get to the 
STOP instruction. You can also use the UBR command as described in the 
breakpoints section. If you cannot get out of domain 0, Type OSQUIT to clean 
up. 


The ground rules are do everything you can to terminate processes normally. 
If you blow up in an application, type G to terminate cleanly. After looping, 
type PC 0; G to again terminate the process cleanly. Use QSQUIT as a last 
resort, and that means only in domain 0. You should never have to reset the 
machine using the reset button on the back of the machine. 
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The PL/PL duap 


Frequently, a bug report will come with a three page printout that was made 
with the PU or PL LisaBug command. This command generates output similar to 
pages 1,2, and 3. The first page consists of a screen dump of the primary 
screen, the second page contains the screen dump of the alternate screen, and 
the third page has some additional stack crawl and memory locations displayed. 


There is a wealth of information provided in these three pages. The first 
page gives us a big hint; some item from the arrangement menu was being 
executed. The second page gives us additional information. A bus error was 
detected and the access address is 0. This is a big clue because nil pointers 
are O and generate a bus error if you try to access location 0. Also included 
on page 2 is 4 register display, and the most interesting piece of information 
is that the program counter (PC) was at SUBFMOLS+94 at the time of the bus 
error. Note that the first line of the register display is Level 7 interrupt. 
This is basically a worthless piece of information, as fer as applications sre 
concerned. This is because NMI, address errors, and bus errors always show 
level 7 interrupt. 


The third page of the dump gives us four distinct groupings of information. 
The first is a register display, then a stack crawl, then a disassembly of the 
instructions surrounding the PC, and finally a portion of the stack is 
displayed. Using these pieces of information we carn determine what went 
wrong. 


To find out what the processor is objecting to, we start by looking at ( 
SUBFMOLS+94, the location which is at the top of the register display. 

Looking at the disassembly (marked 5 on page 3) we see instructions at 
SUBFMOLS+92 and st +96 but not at +94. Actually, it turns out that the PC 
leads (has already advanced past) the instruction being executed. This time 
the PC leads by 4, and the instruction being executed is at +90. There we see 
@ MOVE.L (AO), (A1). This is marked 6 on page 3. Looking back to the register 
display, we can see that AO looks okay but that Al is O. It is the reference 
Vie Al which caused the bus error. 


There is also some other handy information on page 3. Register A6 points to 
the stack frame (marked 1 on page 3). Matching the address contained in A6 
with the stack display, we can find the parameters to SUBFMOLS. The address 
is marked 2. The first 2 words at that address link to the calling stack 
frame and the return PC for the calling procedure. Following that are the 
peremeters in REVERSE order (marked 3). See the section on Paremeters for 
more details. 


One final note on the using the PU and PL commands. These commands use 6 
Parallel printer connected to Slot2Chan2 or Slot2Chani respectively. They do 
not work with serial printers. The commands should be used immediately 
following an occurrance of 4 bug so the error display is preserved. If you do 
a stack crawl and the call is pretty deep, the stack crawl can wipe out the 
error display, making the information on the alternate screen less valuable. 
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Finding out what parameters are passed and returned 


Page 4 shows @ more dynamic tracing of the seme bus error. The first command 
used is the display memory command. Its arguments request using A6 indirectly 
to display 40 hex words. The next command TD gives the register display. The 
SC (stack crawl) command gives the trace back of who called whom. 


So let's find out what parameters were passed to GEMenuCmd. This routine has 
the calling sequence written in to the right of the stack crawl command. To 
find the parameters we find GEMENUCN in the stack crewl display, and look down 
one line to find out the stack frame. The stack frame is at F7BE88. This 
part of memory was then displayed using the DM command. The first word 
contains F7C21E which is the stack frame pointer for GeMenuEvent. The next 
word is an address, and using the CV (convert) command shown at the bottom of 
the page, we see that this is the address of GeMenuEvent+492 which is the 
instruction in GeMenuEvent immediately following the call to GEMenuCmd. 


Following the return PC, the stack has 0007 and 0006. The parameters are in 
reverse order so item is 7 and menu is 6. 


This exemple shows a very simple case, one where two integers were passed hy 
value. Now we'll do ao more complicated example. Page 5 shows the calling 
sequence for the Select routine in the Field Editor. First 4 breakpoint was 
set at Select+3 and then the register display is shown when the breakpoint was 
hit. (See the breakpoint section for more info on breakpoints). Once inside 
the Select routine (and past the Link instruction -- more on this in 
breakpoints), we proceed to display memory pointed to by AG. Remembering to 
skip the stack frame pointer and the return PC, the next word is the LAST 
parameter to Select, and it is F7F3ZE. This is an address because it is a var 
parameter -- so F7F32E is a pointer to t. Continuing, F7EE32 is a pointer to 
n; D60552 is a handle to a field state; D6054E is a handle to the field: The 
point consists of the next two integers 85 and 141. 


Now let's assume we want to look at the field, and specifically, what the 
value of the field is currently. To do this, we have the handle to the field, 
and the record declaration of the field. We can use the DM command toa look at 
D6054E and then access the first longint there D623d4 to get to the field or 
we can use the shorthand DM (0D6054E) to get in one step to the field. The () 
means “indirect”. 


Examining the field, the coords rectangle is the first 4 words; maxlen is 8; 
growlen is 8; curlen is 1; align is 3, drewpad is 4 — both packed into one 
integer; curvalue is E20802. Now we access curvalue to get the contents of 
the array. Looking at the display, the first byte is a lowercase g. We know 
that since curlen is 1 that is all the field contains. 


There are a couple of other observations we can make. We can examine where 
these heaps map to data segments. Looking at the curvalue array we know that 
it is pointed to by the handle E20802. Knowing that the master pointer and 
the handle are in the same segment, using the first byte of the address, we 
can calculate the MMU number. £2/2 gives &113 which corresponds to LOSH 7. 
(LDSN 1 starts at 107, LDSN 2 is at 108 ...). Doing a Stop-Start calculation 
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( 
we see that the segment is 8K long and the handle, at 802 is at 2% into the 
segment, a valid address. 


Note that 2 heaps (and segments) are being used here by the graphics editor. 
The field data structure is in one heap D6xxxx addresses and the other is used 
for the data components of the field and have addresses of E2xxxx. This is 
not the usual way of using fields and heaps, but see what you can figure out 
using LiseBug! 


Breakpoints 


Breakpoints when debugging applications are useful when in the application's 
domain. This is noted on the register display. Note that domain O or another 
domain overridden to 0 are not application domains, and you cannot set 
breakpoints in the application there. There is one special case. When in the 
application process, but in domain 0 (the case indicated with the brace on 
page 6) you can use the UBR (user break) command. This sets a breakpoint at 
the first instruction in the user domain, and starts executing. In the case 
on page 6, the breakpoint is reached at LetOthersRunt34. From this location 
you are in a user domain (domain 3) and in your process (process id 6) and can 
set breakpoints. I did 4 stack crawl to show that the application symbols are 
avallable at this point. Next I did a CL PC to clear the breakpoint where I 
em currently stopped. 


There are & few rules to remember to follow when setting breakpoints. First ( 
you should never set breakpoints on IUJSR or the future ILJISR instructions (or* 
ary other IUxxx or ILxxx instructions}. However, you can trace through them 
if you don't mind seeing all the code for the trap handlers. They do not 

work, and will give unpredictable results. Many people have wasted hours of 
time because of this. The second rule is it is frequently desireable to set 
breakpoints after the LINK and before the UNLK instructions. Page 7 shows 

why. After the first register display, two breakpoints were set, one at 
GEMenuCmd, and one at GEMenuCmd+8. I then ran until I reached the first 
breakpoint. Then I did a stack crawl and displayed the stack frame. Then I 
ran again, stopping after the Link instruction is executed. Then I did 6 
stack crawl and a display of the stack frame again. Note that they are very 
different, and the one at +8 gives correct results. I generally set 
breakpoints at the Procedure+8. Note that this only works for code generated 
with a TST.W instruction before the UNLK (the usual case, but is not 
guaranteed) . 


To set breakpoints at the end of the procedure, you will have to use the IL 
command to find the end of the procedure. You can usually spot this because 
UNLK...RTS sequence followed by the procedure neme dropped in the code. An 
example of the end of a procedure is shown on page 4. You can even see the 
procedure name, although the first character is not visable because the high 
bit is set to indicate to LisaBug that this is a Pascal procedure. Setting a 
breakpoint just before executing the UNLK instruction will permit you to 
examine the var parameters that are being returned in exactly the way the 
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input parameters were determined. However, to use this technique, beware of 
nested procedures and global gotos. 


So far we have always used symbols for setting breakpoints. Sometimes it is 
not always possible. Sometimes the code is swapped out and LisaBug cannot 
find the symbols, or the code was compiled without symbols. Then you will 
have to use & logical address to set the breakpoint. The usual way of finding 
out the address is to find the IUJSR call to the routine and break on the 
target address. Another technique suggested by Chris Moeller, is to first let 
the progrem fail, then do a CV on the symbolic name, and then rerun the 
program setting the breakpoint at the logical address. 


To set breakpoints when the progrem is coming up, you have to use a few 
tricks. First, you'll run the Office System under the OS shell (or Workshop 
shell if you have compatible libraries). Then you use the Debug command, and 
respond shell .office sytem for the program, and yes for the question to debug 
all sons. Then each process launch will give you an opportunity to set 
breakpoints. These breakpoints may have to be logical addresses because the 
probability of the code being in memory is very low (unless the OS has left 
the program loaded). Note that this technique of remembering logical address 
across process executions only works for the exact seme program. Relinking 
the program will invalidate the logical address assignments and you will have 
to let it break first, find out the logical address, and then rerun and set 
the breakpoints. 


An alternative suggest by Rod Perkins is to bring up the filer, hit NMI 
opportunely in domain 0, then set a4 breakpoint on O:Declare_Excep_Hdl. When 
it stops at the breakpoint (in domain 0), issue CL PC to clear the breakpoint, 
Then issue the UBR command. It will then break in your application. 


Local and Global Variables 


It is frequently useful to be able to trace through a routine and determine 
what the value of some variable is. To do this, you need to understand the 
layout of the stack. Page 8 shows a diagram of the stack. Note that in this 
diagram, the addresses go from low to high. Global variables are accessed by 
adding negative numbers to AS, and local variables are accessed by adding 
negative numbers to A6. Intrinsic unit globals are accessed by first adding 
positive numbers to A5 to get to the data pointer table entry, and then taking 
the value found there and adding negative numbers to that. 


To show how you can figure out values of local and global variables while 
stepping through a procedure, I picked out a very small procedure. Its source 
listing is on page 9. Page 10 contains the disassembly of the procedure. The 
process of determining where 4 variable is in memory requires some matching of 
the source with the code generated. What I usually do is use the IUJSR 
instructions to determine rough areas of code and then look in more detail at 
the generated code from there. 


Page 10 also sets a breakpoint at copysel+8 and runs until the breakpoint was 
hit; then the stack frame was printed out. Note that the CutCopyField 
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procedure is not in memory. We can tell that by the fact that at CopySel+5C 
there is an IUJSR to $8E000E instead of CutCopys. 


Looking on page 11, we see that an ID of $6E000E gives the invalid logical 
address message. To illustrate setting a breakpoint on a logical address, I 
set a breakpoint at $8EO00E. Also a breakpoint was set at CopySel+14. 


At the CopySel+14 breakpoint, we are about to compare TypeofSel with 
a@ellTxTSl1. TypeofSel is a Variable of an enumerated type, and aCellTxTS1 is 
one of the values. Its value is 1. So displaying rad+$ffffffc9 displays the 
value of TypeofSel. Note that the instruction is CMP1.B #$0001, $ffc9(a4). 
The DM command uses $ffffffcS because we want to maintain the fact that it is 
@ negative quantity. RA4+$ffffffc9 yields Of7cf49, an odd address. Note that 
LisaBug. however, starts the display at Of7fcf48, so the byte we are testing 
is the rightmost byte of the first word. Note also that the access is 
relative to A4, but that A4 was loaded relative to AS. This is because this 
is a global variable in an intrinsic unit, and A4 contains the pointer to the 
base of the globals for this unit. 


At CopySel+24 we access another intrinsic unit global, this time it is 
tblpars.editcoltitle. It is again at an odd address. The variable is a 
boolean, and hence its value is true. 


At CopySel+3E we are pushing a parameter to SetPnilPort. It again is an 
intrinsic unit global. The parameter is an integer, and displaying the value 
shows it to be 3. Next, the trace command was used to step to the next 
instruction. Note that the value of A? has changed, and that A? points to the 
value just pushed on the stack. 


On page 12, we are pushing the effective address of a local variable, errnum. 
Note that the reference is relstive to AB. When the value is displayed, its 
value is BF52 (garbage since its value is set by the routine). 


Continuing on, we hit the breakpoint at $B8EOOOE. This is a digression from 
the flow of finding out the value returned from CutCopyField, so I'1l just 
show how you can get into CutCopyField and get out. This address where we 
stopped is actually a jump table entry, so we trace through the instruction 
and get to CutCopyField. (A jump table is used when calling from one segment 
to another). After a few more traces to get past the LINK instruction, we 
check the address of the last parameter passed to CutCopyField, and it is 
indeed the address of errnum we found before. Next, a breakpoint was set to 
the return PC. 


After continuing, we break in CopySel immediately after the return from 
CutCopyField. Displaying the location containing errnum, we see CutCopyField 
returned 0000. | | 
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internals @ Confidentisa? 


Function returns 


It is frequently useful to determine what a function returns. To do this 
break at the instruction immediately following the JSR or IUJSR to the 
function. Then the function return is on the top of the stack. DM ra7 will 


display the returned value. 
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a tit! cs ||| 
a 


Text ; . 
| ; . BE 
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bbe haters | me reterences ipboard ge Disk 


Racsessssedte oonetocsse 


wo -evgvsr7 


a 

Level 7 Interrupt 

SUBFMOLS+0894 8608 5340 ORI.B #$5340,AG 
PC=@8281A32 SR=8@000 O US=OGF7BDCC SS=@@CBFEDS DQ=1 P#=@0007 
De=@0G80002 D1=@0000108 D2=OGGOFFCE D3=@6DG07E4 

D4=0C280005 D05=80145788 D6é=B666B8GA D7=BBDABABS 

AG=GBDABABS A1=GOB8G088 A2=GECEGB4C AS=GGF7F 466 

A4=Q@OF7F 466 AS=OGF7F4A6 AG=OOF7BDDS A7=GOF7BDCC 


»pu 

x 

BUS ERROR in process of gid 7 

Process is about to be terminated. 

access address = 6 = wmnu# Qo, offset 


inst reg = 8848 sr = @ pc = 2628146 
Saved registers at 13369270 é 
Going to Lisabug, type g to continue. 


Level 7 Interrupt 


SUBFMOLS+0094 0008 5340 
' 00281A32 SR=0000 0 US#00F7BDCC SS=00CBFEDS 


PC 


OR] .B 


‘  ym00000000 D1=00000100 D20000FFCE D3=000007E4 
D4=0C280005 D5=00145700 D46=0000000A D7=00DA0AB8 
AD=O00DADABE A1=00000000 AZ2=00CE004C AI=00F7F 466 
A4=00F7F466 AS=OOF7F4A6 feSone anes) Aiaver ae 
At OLS+0094 Oo 


Stack fran 
Stack frame 
Stack frame 
' §tack frame 
Stack frame 
Stack frame 
Stack frame 


7BDD8 called 
at OOF7BE14 called 
at OOF7BE2E called 
at (OOF7BE68\ called 
at OOF7C2IE called 
at OOF7C238 called 
at OOF7C298 called 


from COMMITLA+033A 
from LOCKCMD+007A 


¢rom GEMENUCM+02A0 | 


from GEMENUEV+048E 
from PROCESST+011E 
from MAINPROG+008A 
from GRAPHICS+001E 


#$5340 ,A0 
DO=1 P#=00007 


Stack frame at 00F7F4A6 


SUBFMOLS+0074 2968 0004 0004 MOVE.L $0004<A0) ,0004(A4) 
SUBFMOLS+007A 4016 BRA.S  #+$0018 ; 00281A30 
SUBFMOLS+007C 2047 MOVE.L D7,A0 
SUBFMOLS+007E 2247 MOVE.L D7,Al 
SUBFMOLS+0080 2251 MOVE.L (Al) ,Al 
SUBFMOLS+0082 2368 0004 0004 MOVE.L $0004(A0) ,$0004<A1) 
SUBFMOLS+0088 2047 MOVE.L D7,A0 
SUBFMOLS+006A 2247 MOVE.L D7,Al 
SUBFMOLS+008C 2269 0004 MOVE.L $0004<A1) ,Al 

3 5090) 2290 MOVE.L (AO) AII® 

5) (SUBEMOLS* 0092) 302C 0008 MOVE.W $0008(A4) ,D0 
SNIQFMOLS+0096 5340 SUBG.W #$1,D0 

( _-FMOLS+0098 3940 0008 MOVE.W 00,$0008(A4) 
- gUBFMOLS#009C 4267 CLR.W (A?) 

SUBFMOLS+009E 2F07 MOVE.L 07,-<A7) 
SUBFMOLS+00A0 4EBA F10A JSR CNTOFOBJ ; 00280B4A 
SUBFMOLS+00A4 302C 000A MOVE .W $000A<A4) ,DO 
SUBFMOLS+00A8 905F SUB.W (A7)+,D0 
SUBFMOLS+00AA 3940 000A MOVE.W 00 ,$000A<A4) 
SUBFMOLS+00AE 42A7 CLR.L  -<A7) 
0OF7BDB8 QOF7 BEO2 002A 353C O00F7 BDEC O0OF7 EBSS .....#5<....006. 
OOF7BDC8 QODA OASC 0000 0001 _00DA 0A64 OOFB 04B6 ...1esseeeedeees 

@ (OF7BDDs\ (GOF7 BE14 002A 2764(Q00DA DABS OOF? F4dd .....8#/d... see 
OOF7BDE8 0000 000A 0000 0197 O0DA 0AS4 OOFS 04B6 ....ceeeeeeGeees 
0OF7BDF8 0002 0088 SFC2 00DA OABS OOF7 BE12 002A ...s_eeeeeeseeet 
0OF7BE08 35A8 0000 0000 0000 0000 OOF7 OOF7 BEZE S....cceeeeeeees 
0OF7BE18 0062 0888 0014 5700 0000 0001 0000 0007 .b....We.sseeees 
00F7BE28 BE30 0036 3316 OOF7 BEBE 0064 1400 O1GE .0.63......d..6n 


Lise Bun-3 


PARAMETERS | ‘PD 


>dm rad 40 

OOF 7BDDS OOF7 BE14 002A 2764 OODA DABS OOF7 F466 .....8’Gi ce ceef 

OOF 7BDES 0000 GCOOCA 0000 0197 ODODA 0A64 OOFS 04B6 .. cc cn ccc cGeree 

‘ 7BOFS 0002 0088 SFC2 00DA OABS OOF? BEI2 O02A ...._csccccceertl 

Our 7BE08 35A8 0000 0000 0000 0000 OOF? OOF7 BEZE SS... .csecccvsees (. 
td . 
SUBFMOLS+0094 0008 5340 PC ORI.B $5340 ,A0 


PC=00281A32 SR#=0000 O US=00F7BDCC SS=00CBFEDS DO=1 P#=00007 
DO=00000000 D1=00000100 D2=Q000FFCE D3=00D007E4 
04=0C280005 D5=00145700 0é6=0000000A 07=00DA0AB8S 
AD=00DADABS Ai=00000000 A2=00CED04C AI=00F7F 466 
A4=00F7F 466 AS@00F7F4A6 AS=@OOF7BDDS A7=00F7BDCC 


sc . TT j 
At SUBFMOLS+0094 GemenuCad Cmomt, tem * Juteser ) 
Stack frame at OOF7BODS called from COMMITLA+033A 
Stack frame at OOF7BE14 called from LOCKCMD+007A 

Stack frame at OOF7BE2E called from (GEMENUCM+02A0) 
Stack frame at QOF/BE86) called from GEMENUEV+040ES 
Stack frame at_DOF7C21E called from PROCESST+011E 
Stack frame at/0O0F7C258 called from MAINPROG+008A 
Stack frame ati OOF7C298 called from GRAPHICS+001E 
Stack frame at\00F7F4A6 


Ydm 047be88 

0OF7BE88 (0007\10006)0C28 0002 ....sdees eee hes 

0OF7BE98 0014 S7CO 2F00 4267 2F2E FFD4 201F 0A01 ..W./.Bo/....... 

OOF7BEA8 OOF8 04B6 0001 1453 4574 2041 7369 6465 .......Set.Aside 

>i} 6418de-20 

GEMENUEV+0472 FFDC $35 

GFMENUEV+0474 486E FFD2 PEA $FFD2(AS) See 

{  ENUEV+0478 486E FFD4 PEA $FFD4(A6) 
GEMENUEV+047C A088 02B4 1UJSR  MENUSELE : 008861AC ( 
GEMENUEV+0480 4A6E FFD4 TST.W 9 $FFD4(A6) 

GEMENUEV+0484 670C BEQ.S  #+$000E : 006418DC 

GEMENUEV+0486 3F2E FFD2 MOVE .W  $FFD2(Ad) ,-<A7) 

GEMENUEV+048A 3F2E FFD4 MOVE .W $FFD4(A6) ,-<A7) 

GEMENUEV4048E 4EBA F862 JSR GEMENUCM ; 0064115C 

GEMENUEV+0492 4267 CLR.W  -<A7) 

GEMENUEV+0494 A088 022A IUJSR  HILITEME ; 00885C18 

GEMENUEV+0498 4CDF 18F0 MOVEM.L (A7)+,D4-07/A3/A4 

GEMENUEV+049C 4E5E UNLK  A6 

GEMENUEV+049E 2E9F MOVE.L (A7)+,(A7) 

GEMENUEV+04A0 4E75 RTS 


GEMENUEV+04A2 C745 4045 4E35 4556 0060 2000 0000 0000 .EMENUEV.*...... 
GEMENUEV+04B2 0000 0000 0000 0000 0000 0000 0000 D000 ...cesceccecceee 
GEMENUEV+04C2 0000 0000 0000 0000 0000 0000 0000 0000 .....crceceeeaes 
GEMENUEV+04D2 0000 0000 0000 0000 0000 0000 0000 0000 ....csersunsecee 
GEMENUEV+04E2 0000 0000 0000 0000 0000 0000 0000 0000 ........seeeuees 


Cc 
S TTEDC=E65599 64=GEMENUEV#0492 
Ce 


Ypr 0 


LisaBbeg-4 


Faehew x 


dhe select+8 
{ 


Break Point 

SELECT+0008 #48E7 0118 
PC=008C3FAS SR#0000 0 
D0=00020001 D1i=00E20000 
D4=0010FFFA 05=00000001 
AQ#=00F804B6 Al=00F7F32E 


ZS 


var t:integer); 


A4=00F 80486 AS=00F7F4A6 ASBOOF7C018 A7=00F7C010 


Yam rad 40 

00F7C018 OOF7 C034 002A OS8DE 

0oF7CO028 0006 0532 0006 OS4E 

00F7C038 0062 1884 0062 0085 

00F7CO048 0010 FFFC 397C 0007 

ydm 0d6054e 

00D06054E 0006 23D4 00046 23AE 

Ydm 0d623d4 40 

00062304 GO7E 0138 008A 0140 

00D623E4 OOE2 0802 0001 0001 

00D623F4 4012 034A OO1E FFFD 

00062404 0004 0304 0006 DS53A 

ydm (0d6054e) 40 

00062304 0O7E 013B 008A 0140 

00D623E4 OOE2 0802 0001 0001 

000623F4 4012 054A OO1IE FFFD 

#*NS2404 0004 0304 0006 033A 
a (0e20802) 10 

00E20832 67E2 1FF4 OOE2 IFF4 

rev e2/2 

$712&113=00000071 

mn &113 


OC1] Segment(71) Origin(465C) 
Yev Ocd74F#-0cb800 

$1 FFF2&81 91200001 FFF 
Yev 802 


$0802=&2050=00000802 fiel 


d = record 


coords: 
mepd_en: 


curValue: 


aoents: 


growFnts: 


curFfrts: 
fat info: 
protect: 


00F7 
008s 
0141 
FFFE 


00D6 


0008 
0001 
002A 
0001 


0008 
0001 
002A 
0001 


0000 


F32E 
0141 
O0O0DA 
7006 


2394 


0008 
00E2 
0025 
0001 


0008 
00E2 
0025 
0001 


0006 


hndDota; 
integer; 
integer; 


integer; 
hndRuns ; 
boo! ean; 


end; 
ptrField = “field; 
hndFieid = “ptrField; 


OOF? 
00F7 
0896 
1080 


0006 


0001 
0806 
0008 
0001 


0001 
0806 
0008 
0001 


00E2 


EE32 
CO7E 
397C 
ooFSs 


237A 
0304 
002E 
0008 
0006 


0304 
002E 


00D6 


08446 


ra 
Gat 


Soy 


cueT 


“ s 
re 
ereeesevoecevesn 


0008 O6ibids CREA Cede 


(3) 


procedure Select (dxy:Point; hf:hndField; hfs:hndF State; var n:Rect; 


MOVEM.L D7/A3/A4 ,-(A7) 
US=00F7C010 SS=00CC0000 DO=1 P#=00008 
D2=00000002 DS=001FFFFF 
Dé=FFFC3900 D7=0007FFFE 
A2=00CE004C A3=70061080 


ret errr ree 
oe eRe eNee Aaa” 
Dee Dee Aree eTZI 
con eP been eDovace 


me eras Peewee Sees | 


ae ae eee ee ace 


Ori iicdcc Briers 


Bs ee er Br 


Eee Tere eee a 


Limit{£FO] Control(7] Startf{0CB800) Stop(0CD7FF) 


static field characteristics 

bounding rectangle 

maximum number of chars 
(should equal size of 
curvalue orray) 

size by which to grow value 
array - don't grow if 0 

current number of chars 

alignment of chars when fieid 
is displayed 

* of pixels to draw fron left 

. right (depending on 
ali t 

handie of array of contents 

maximum * of format records 

* of format records by which 
to grow - don't grow if 0 

current * of format records 

handie to array of runs 

true => chonges not al lowed 


LUscBag-5 


00=00000013 Di=GQ000000 D2=00000002 03=001F2714 7 ; 
D4=s2D48F900 DS5=00TDAS4 2048FE00 D7=00000000 Breaky in bs / Damnaaars 
A0=00004004 A1=00CBF 2=00208C04 A3=0020A022 

OCBFF6A A7=00CBFF36 &) 


: @) 7 Interrupt 
00220E62 4COF O08E0 MOVEM.L (A7)+,D5-D7/A3 f 
PO=00220E62 SR=2004 0 US=00F7C25A SS=00CBFFBS 00=0 
00=00000000 Di=O000FFFF D2=000006AS D3=00CE07F3 
O4=001 OFFFA DS=00020000 Dé=00CC4FES6 0700860700 

—AO=O036024E A1=00A84270 A2=00008000 A3=00000400 
A4=00AG426C AS=00CC4088 AS=O00CBFFES A7=00CBFFBS 


9 


Level 7 Interrupt 
@QUEUVE_PR+00466. 0280 ADD.-L 00,01 
PO=00260BF4 SR=0700 O US=00F7DC32 SS=00CC0000 DO=0 P#=00006 
' DO=FFFFB481 D1i=00CCA0GS D2=00000002 D3=00D007E4 ~ = —S—C—~:S 
04=2D46F900. 05=00108004 0é6=2D480078 D7=00F7DCSE 
AO=OOCCAGS2 AL=O0F7DCS62 AZ=OOCEDN4C AZ=0020A022 
A4=00CCBIOE AS=O0CC408E AdB@OOF7DCAC A7=00F7DC32 

— ubr 


Break Point | 
LETOTHER+0034#4ESE UNLK Ad 
PC=0088303C SR=0000 GO US=00F7DC72 SS=00CC0000 DO=3 PH=00006 
D0=00002000 01=00000002 D2=00000002 D>=001FFFFF ~ = 
04=2048F900 D05=00108004 Dé=2D46FE00 07=4AARE0000 
A0D=00F7DC72 Al=O0CCADSS A2=OOCEDNAC AZ=0020A022 
A4=02E46010 Sennen ae A6=00F7DC74 A7=00F70C72 
see ‘ ere. 
LETOTHER+0034 | ; ( | 
Stack frame at OOF70C74 called from MAINLOOP+0196 
:” “Stack “frame at OOF7DCCA called from 00240030 
Stack frame at OOF7FIA4 . 
—> cl pe 
9 


Level 7 Interrupt 

00208C68 - 4840 SWAP DO 
-PO=00208C468 SR=2700 0 US=00F7DC72 SS=00CBFF4A DO=3 overridden 0 
DOR@OOFEOOFE 01=40000000 D2=00000000 D3=00002704 
D4=2D46F900 05=0010CO8D Dé6=2D4SFE00 07=4AARE0000 
A0=0000402C A1=00004000 A2=00208C2C A3=0020A022 — 
A4=802E46010 AS=0000057A A6=00CBFF7E A7=00CBFF4A 
sc 

At 00208Cé48 

Stack frame at OOCBFF7E called from 0020A9A4 
Stack frame at OOCBFFAS called from 0020AA36 
Stack frame at OOCBFFBO called from 0020CC9A 
Stack frame at OOCBFFDC called from 00208466 
Stack frame at OOCBFFFC 


dubr 

Level 7 ince 

00208474 RTS 

,” 300208474 an US=00F7DC72 SS=O0O0CBFFEC DO=3 overridden 0 

- 00000002 D1=000 D2=00000002 03=00D007E4 ( 


A4=02E46010 C A7*00CBFFEC 
dubr 


Level 7 Interrupt Lisa Bug-G 


ARAAALRAA ad od oa MIEN Be OATE AD 8 8 8. 8k a eee 


( 


es fe 
beEeAK torn tS 

dg | 

Level 7 Interrupt ot 

#32.pack+0008 4A02 TST.& 02 


00AC0D76 SR=0001 0 US=00F7C1DC SS=00CC0000 DO=1 PH=000089. 
wu=FFFFOO02 Di=G000000F D2=8000000G8 03=00D007E4 
D4=0010FFFA D5=397C0010 Dé=FFFC397C 07=43180000 
AQ=00F7EBSE Ai=00F7C226 A2=00CE004C AS=00F7E0S4 
A4=00F7EBS4 AS=00F7F4A6. Aé=00F7C20C A7=OOF7C1DC 
>be gemenucrm 
br gemenucm+é. 
»¢ ; 


Breast Point es te ae 7 
GEMENUC+ 0000 #4A6F EFBe. GEMENUCM TST.W  SEFB4<(A7): 
PC20064115C SR=0010. &- US=00F7BESC. SS=00CC0000 DO=t PHe0000S 
DO=OOCOCOFF Di=OCO0CCFF 02=00000002 03=001FFFFF 
04200100005 03=397C00008 Dé=FFFC390G D7=0000000E 
A0=004418CA Al=OOFEOS4A A2=0OCEDN4C AB=700461080 
A4=00F804B6 AS=00F7F4AG AG=00F7CZ1E A7=00F7BESC 

»s¢ 

At GEMENUCTH+0000- 

Stack frame at OOF7C2ZIE called from PROCESST+O11E 

Stack frame at O0O0F7C25SE called from MAINPROG+008A. 
Stack frame at 00F7C298 called from GRAPHICS+00I1E 
Stack frame at 00F7F4A6. 


>dm raé 30 ; 

OOF7C2IiE OOF7 C25& 0064 1F90 OOF7 C22E 206E FFFC 2a cXedecscceeMee 

0OF7C22E COFB 0346 0001 0007 OGOCS 0010 706A 0000 ...H.......spie. 

ONF7C23E 0000 0000 0100 D46AC 0000 0000 0008 0000 ...cecneensesnes a“, 
“Break Point ©— a ee ie ee ee 

GEMENUCM+0008#2F07 MOVE.L. D7,-<A7) 


PC=006411464 SR=0010 0 US=00F7BESC SS=00CC0000 DO=1 PH00008 
DO=QOOOCOOFF Di=O00000OFF D2=00000002 D3=001FFFFF 

D4200100005 DS5=397C0000 Dé=FFFC3900 D7=0000000E 

AQ=006418CA AL=OOFEOS4A A2Z=O0CENDD4IC AS=70061080 

A4=00F 80486. AS=OOF FAAS Aé=00F7BESS. A7=00F7BESC 

se 

At GEMENUO1+0008 

Stack frame at OOF/7BESS called: from GEMENUEV+048E 


Stack frame at GOF7C2Z1E called from PROCESST+011E 


Stack frame at 00F7C258 called: from MAINPROG+008A 
Stack frame at GOF7C298. called from GRAPHICS+001E 
Stack frame at O00F7F4Aé6 


>dm raé 30 

OOF 7BE88 OOF7 C21E 0064 18DC O000B 0004 0010 FFFA .....deccrcsceee 

OOF 7BE9S 397C 0010 FFFC 397C 0007 FFFE 7006 1080 91....91..cePoee 

00F7BEAS GOOFS 0486 OOAC 14353 6574 2041 7369 6465 .......Set Aside 

>il gemenucm 

GEMENUCM+0000#4A6F EFB4 GEMENUCM TST.W SEFB4(A7) 

GEMENUCM+0004 4E56 FFB4 LINK Aé , #SFFB4 

GEMENUCM+0008%2F07 PC MOVE.L D7,-‘A7) 

GEMENUCM+000A 3E2E 0008 MOVE .W S0008C(A6) ,D7 

CEMENUCM+O00E. 4EAD 096E JSR SETWRKOR 3 003632DE 
MENUCGM+0012 302E 000A. MOVE .W S8000ACAd) ,DO 

GEMENUCM+0016 53540 SUBQ.W #$2,D0 

GEMENUQ4+0018 6800 02C2 BMI #430204 3; 00641438 

GEMENUCM+001C 0040 000A CMP! .W #6000A,D0 

GEMENUCQ1+0020 6E00 02BA BGT #4$02BC 3 00641438 

GEMENUQH0024 E348 LSL.W  #6$1,D0 

GEMENUQ1+0026 3038 0006 MOVE .W #480008¢D0.W),DO ; 0064118A TT Oe | 
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Tt ee eee eee os 


low address 


Stack Segment Layout 


$F 80000 


(8) 


Shared IU Globals 
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—_s 


(SS smgrLoUse } yae 
PROCEOURE CooySel(sestus : 


integer }; 

VAR erernum : integer; 

3EGIN 

IF TesceSMGA shen Weiteln('Xtmsprses CapySel’ ); 

if (typeofSel = aCellTxTSt) or 

eu ipsee esicnsericts and (suesorse! z Sale or 

th lPars.EditRowTitle and (typedFSel 2 aRowriedS!)}) then 
Begin 


SeePn lPore(AidePn | ); e 
CurcConyF ield(wavF ieldH, savFseacen, False, crue, errsum); 
Status :2 erenum; 


ENO; 
£n0; 


CucCopyf ie!d(selFieldH, selFstacer, faise, false, erenum); 


COPYSEL+0008 *48E7 0018 


PC=O0O0SS6OSEC SR=0000 O US=O00F7BEES SS=00CC0000 DO=1i P#-00005 


00=00000000 Di=00000000 
D4=000E2F2D DS=FAEASFO7 
AG=005214C0 Als=00F/7BEEO 
AS=00F7D766 AS=00F7F73A 


»dm rad 40 
OOF /7BEEA 
OOF 7BEFA 

. F7BFOA 
'. JF7BF1A 
»pr 0 


OOF? BFS2 
4EAD 0005 
OOOE 2F2D 
OOF7 BF3S. 


MOVEM.L A3/A4,-(A7) 


D2=00000000 DS=001FFFFF 
Dé6"A03C0005 D7=4EAD000S 
A2Z=00SSSC00 AS=00FS04B6 
Aé=00F7BEEA A7=00F7BEES 


0052 150C 
QOF7 D766 
4E01 0002 
008s SDOE 


OOF? BFSO ADSC COVE 
OOFS 0486 OOF7 BFOO 
OOFS 04846 OOF? DF26 
GOF7 0000 0002 O0IF 


a ED I LD ID LO, LS AS ES SD SE ON OLS ES LY LS SLL SS TS Se ied 


cae RaRive walsh oS es 
Nivea edie? 6 69 wes 


eet WNecccsccee c& 


ee Os od oes 0 Gees 


Liss %g-lO 


.i1 cppyset . 
COPYSEL+0000: 4A6F EFFE COPYSEL TST.W SEFFECA7> 
COPYSEL+0004 4GES6é FFFE - LINK AS, #6FFFE 
rFOPYSEL+000S 46E7 0018 MOVEM.L AS/A4G, -(A7) 
- PYSEL+000C 2660 02A0 :- MOVE.L S$02A0¢6AS) ,AF 
_ COPYSEL+0010 266D a29Cc ° MOVE.L $029C(ASD Aa ( 
COPYSEL+0014 0OC2C 000t FFCS CMPI.8 #60001 ,SFFC9<(A4) 
COPYSEL+O001& S7€0 . SEG DG. 
COPYSEL?001C acec cacy FFCS - CMPI.B #60009,SFFC9( Ad) 
COPYSEL+O0022 3S7Ctr —? . SEQ Dt 
COPYSEL+002¢@ C228 FFDE tf 78 _ ANOD.B SFFDBCAS) ,DL 
COPYSEL+0028 s001L OR.B Or 00: 
. COPYSEL+002A ac2c ac0s FFCS . CMPL.B . #60008, SFFC9CA4S) 
COPYSEL+O003SC0 S/7CE . , Be ae SEG. OL 
COPYSEL+0032 C228 FFE2 aa AND.B SFFE2ZCAS) ,DL 
COPYSEL+0036 s0o0cr a OR .Bi 01 ,Dd 
COPYSEL+003@ a24e coat ? ANDI .W #80001 ,D0: 
- COPYSEL+O003C 673A: BEG.S #+$003C 3 0056065C 
- COPYSEL+003E 3F2B FFCC MOVE.W SFFCCC(AS) .-(A7> 
COPYSEER+0042 acoso or7o IUJSR SETPNELPO 3; GOSOOSSE 
COPYSEL+004464 2F2C F442 MOVE.L SF442¢(A4) ,-(A7) 
>iE . 
COPYSEL+004@ 2F2C F43SC MOVE.L SF43C(A4) ,-(A7) 
COPYSEL+004E 4267 ' CLR.W —-¢(A7> 
COPYSEL+0050 i1F3C oOOt MOVE.B #80001 ,-<A7) 
COPYSEL+0054 486E FFFE PEA SFFFECAS) 
COPYSEL+00S@ AOSE O00E IUJSR: - SOOSEOOOE 
COPYSEL+00SC 206E a0c0Ss. MOVE.L S$0008¢AS) ,AD 
COPYSEL+0060 S3O0AE FFFE MOVE .W SFFFECAS) ,<A0>) 
{PW YSEL +0064 -2F2C FFC4-. MOVE.L SFFC4C(A4S) ,-(A7) arees 
_ ,PYSEL+0068 2F2C F44E MOVE.L SF44EC(A4) ,-(A7) ( 
COPYSEL+006C 4267 CLR .W -(A7) 
COPYSEL+006E 4267 CLR .W -(A?7) 
COPYSEL+0070 486E FFFE PEA SFFFECAS) 
COPYSEL+0074 ACGSE OO0E IUJSR sO00S8SE000E 
COPYSEL+0078 4CDF 1800 MOVEM.L (A7)+,AS/AG 
COPYSEL+007C 4ESE UNLK AS 
‘COPYSEL+007E 2E9F MOVE.L. (A7)+,<A7) 
COPYSEL+008S0 4E795 RTS. 
COPYSEL+008S2 C34F SOS? S345 4C20 0000 4A6F EFFE 4ES56 .OPYSEL...Jo..NV 
CUTSEL+0000. 4A6F EFFE CUTSEL. TST.W SEFFECA7>) 
CUTSEL +0004 4E36 FFFE LINK AS, #SFFFE. 
»br copysel+e 
9 
Break Point 


ey > ee, 


- et ee; 


id 8e000e 


Invalid tog addr 
»br 8e000e 
»br copysel+i4 
9 


Break Point 

COPYSEL+0014 #0C2C 0001 FFC? CMPI.B #80001 ,SFFC9<A4) 
PC=00S60SF6 SR=0000 GQ US=00F7BEEO SS=00CCO000 DO=i PH=00005 
00=00000000 Di=00000000 D2=00000000 DS=00!1FFFFF 

O4=000E2F2D DSe8FAEASFO7 Dé=A03CO000S 07=4EAD0005 

A0#=00S214C0 AlLs00F7BEE0 A2Z=00SSESC00 AS=00F7D765 

A4e00F/7CFS0 AS=@00F7F73H AG=@O0OF7BEEA A7=00F7BEE0 


> +BFF4FFFFC9 
OF 7CF48 6101 ooOCc 
>br cop 1424 


9 


Break Poin 
COPYSEL+00 
PC=00360608 
DO=OOOO000FF 
D420 00E2F2D 
€0=005214C0 
' wOOF7CFSO 


( »dm SttF 
OF7D790 >. - 
CU rest+stFF 


*C22B FFDB 
Sk=0009 0 

i=00000000 
S=FAEASFO7 
i=Q0F/7BEEO 
S=00F7F73A 
#f#db 


SF 70741816242 


9101 0100 


ev Pinal 62024@7Q0F70741) 


0010 GODS O72E 0ODS 0746 OODS ....cccevceeeFe. 


AND.B SFFDBCAS) ,DI 
US=Q0F7BEEO SS=00CCO000 DO=i P#=00005 
D2=00000000 D3=001FFFFF 
Dé=A03C000S D7=4EAD000S 
A2=0088SC00 AS=00F7D7465 | 
A6=00F7BEEA A7=00F7BEES "Kad 


oe0!i 9106 OOOO 0001. 0OCO BO4G ow eeeeeeeeee eH 


OOF 7D741 


SF7CF49mu 1 624045 7=Q0F 7CF4D 


>br copysel +3e 
3 


Break Point 
COPYSEL+003E #3F25B FFCC 
PC=00560622 SR=0000 0 
DO=00000001 Di=#=00000000 
D4=Q000E2F2D DS=FAEASFO7 
A02=005214C0 Al=00F7BEE0 
A4=00F7CFSE0 AS=@00F7F73A 
>dm raB+StFFtFFF 


O0F7D732 (0003 | 


>t 

COPYSEL+0042 AOSD 0170 

PC=00560626 SR=S0Q0 0 

Do=00000001 D1i=00000000 

— O4m000E2F2D DS=FAEARSFO7 
3=005214C0 Ai1=O00FABEEO 

AS=00F7CFS80 AS=00F/7F73A 


:>dm ra7 
OOF 7BEDE (oo0s | 
»br copysel +54 


9 


002 


Trace Point 


DOFS 


MOVE.W SFFCC(AS) ,-<A7) 
US=00F7BEEO SS=00CCO000 00=1 P#=00005 
D2=00000000 D3=001FFFFF 
Dé=AG3C000S D7=4EAD00NS 
A2=0088SC00 AS=00F7D746 
AS=@=OOF7BEEA A7€Q0F7BEEO> 


0001 0000 90001 0100 0101 Q101 rr ee ee 


\ 


IUJSR  SETPNLPO ; 0OSO089E 


US=O0O0F7BEDE SS=00CCO000 DO=1 |/P#=00005 
D2=00000000 D3S=001FFFFF 
Dé=A03C0005 D7=4EAD000S 


Lise Bac lt 


—s we wesw 


COPYSEL+0054 #486E FFFE PEA SF FFECAS) 
_pPCm00560638 SR=0000 O US=00F7BED4 SS=00CC0000 DO=1 P#=00005 


Do=00000000 Di=00000000 
D4=000E2F2D DS=FAEASFO7 
AD=0056062A AL=O0F20BEC 
¢*sQO0F7CF80 AS#00F7F73A 


,, fie 
(orsz dor? 
Yam PUsesFFFe Pree 


Break Poi 

OOSEOCOOE *#4EF9 OOSE 
PC=O0OSEOOOCE \SR=0008 0 

00=00000000 O&1200000000 
D4=2000E2F2D DSeFAEASFO7 
ADZO0SS6062A AILROOF2Z0BEC 
AS#00F7CFS80 AS#@=Q0F7F73A 
>t 


Trace Point 


D2=00000000 D3=001FFFFF 
Dé—=A03C0005 07=4EAD0005S 
A2Z=O0088S5C00 AZ=00F7D7S66 
AS@O00F/7BEEA A7200F7BED4 


((-) 


BFS2 0052 i150C OOF? BFSO AOSC .R...R.R.....P.< 


068E JMP 


D2=00000000 D3=001FFFFF 
Dé6=A03C0005 D07=4EAD000S 
A2Z=0088SC00 AS=00F7D7466 
AS6=00F7BEEA A7=00F7BECC 


SO0SE0S68E 
US=00F7BECC SS=00CCO000 DO=1 P#=00005 


C 


CUTCOPYF+0000 4A6F EFDO CUTCOPYF TST .W SEFDOCA7) 
PC@O0O0SE0SSE SR=8008 \0 US=#00F7BECC SS#00CC0000 DO=i P#=00005 


bo#00000000 D1i=z00000000 
D4zQ00E2F2D DS=FAEASFO7 
AD#005S0S52A A1IZOOF2Z0BE 
A4@00F7CFS0 AS=00F7F73A 
:>t 


Trace Point 
CUTCOPYF+0004 4E56 FFDO 
” ws2Q08E0692 SR=G000 <0 
vv200000000 01=00000000 
D4eQ000E2ZF2D DS#FAEASFO7 
AD=ZO0036062A A1z00F2Z0BEC 
A4@00F7CFS0 AS@00F7F73A 
2>¢t 


Trace Point 
CUTCOPYF+0008 48E7 0318 
PC2=008E0696 SR=Ss000 0 
00=00000000 Diz00000000 
D4z2000E2F2D DS#FAEASFO7 
AD#0036062A A1zO00F2Z0BEC 
A4=00F7CFS0 AS=00F7F73A 
:>dm rad 
OOF7BECS 
>br 369640 
7g 


Break Point 


OOF/ BEEA [0056 0640 


D2=00000000 
D6=A03C0005 
A2=0088SC00 
AS=00F7BEEA 


US=00F 7BECC 
D2=00000000 
062A03C0005 
A2=008a5C00 
AS=00F7REEA 


US=00F7BE98 
O2=00000000 
Dé=A03C0005 
A2=00885C00 
Aé=00F7BECS 


COPYSEL+005C *206E 0008. 


OOF7 BEES 


D3=001FFFFF 
07=4EAD0005 
A3=00F 707456 
A7=00F7BECC 


LINK AS, #S8FFDO 
SS=00CCO000 DO=!1 P#=00005 


D3=001FFFFF 
D7=4EAD0005 
A3=00F7D766 
&7=00F7BECC 


MOVEM.L D6/D7/A3/A4,-(A7) 
S=00CCO000 DO=1 P#=00005 


N3=001FFFFF 
OV=4EAD0005 
AMWX=O0F7D766 
A7*OOF7BE98 


J MOVE.L %40008¢A6) ,A0 
PC=00560640 SR=0000 6 US=O0F7BEE0 SS=00CCO000 DO=1 P#=00005 


D0=00002700 doa de ede D2=00000002 D3=001FFFFF 
EAS 


D4=000E2F2D D0S= 


FO7 Dé=A0SC000S D07=4EAD000S 


A0=00560640 ef=00ccs4cc A2Z=00CE004C AS=O00F7D746 
A4=00F7CF80 AS=00F7F73A AS=00F7BEEA A7=00F7BEEO 


. 4 fF 44444 
UUF7BEE 0O0F7 BF52 0052 150C OOF7 BFSO AOSC .....R.R....-P.< 


>9 


DiFS o0Cdd 


7 


er ee eae ae es 


LisaBag- [2 
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Shell-Writer's Guide 


This document contains information you need to know to write a shell for the Lisa. 

It describes the things a shell must do when it starts up and when it terminates. To 
use this document, you should be familiar with the Goerating System Heflerence 
Manual and have some knowledge of Pascal. To do any graphics, you will have to 
use QuickDraw, described in the Fascal Reference Marual You may also want to use 
calls in the PaslibCall and PPaslibC units. 


The System-shell 


When the OS is booted, it starts the 'root' process, which searches the boot disk for a 
shell called 'system.shell’. The system-shell is automatically started, and will be the 
ancestor of all other shell processes (see Figure 1). Al] shells must be “plug- 
compatible” with each other so that any shell can be the system-shell without special 
support from the QS. In this way, a turn-key boot disk could be prepared that didn't 
include a selector shell. 


System.shell 
(Environments window) 


one gram) \ (Cooma 
OS shell still more 
(UltraDos) 7 shells 


Figure 1 
Process Picture 
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If your shell is the first process (the system-shell), you must make the following 
systern initialization calls. Normally, the selector shell takes care of this for you. 


Startup: procedure BlockDinit; Initializes Pascal 1/0. (Note: if you don't have 
the privileged PASLIB interface, declare BlockIDInit external.) 


procedure PMinit (var error: integer); Initializes parameter mernory. 
(Note: you have to be able to link against the pmm unit to 
make this call.) 


function enableDbg (on: boolean): boolean; Activates LisaBug if you 
want to use it. 


procedure setNMikey (keyCap: integer}, Makes LisaBug accessible 
through the NMI key. 


Termination: procedure BlockIODisInit; PASLIB cleanup. (Note: if you don't have — 
the privileged PASLIEB interface, declare BlockiOlInit external.) 
To tell if your shell is the system-shell, call: 
info_process (OSErr, My_Id, Pinfo) 
If Pinfofather_id is i (the root process), then you're in the system.shell. 


The Environrnents window is the standard system.shell It scans the directory of the 
startup disk for files whese names begin with 'shell.'. For your shell ta be recognized 
and available from the Environments window, the name of its object file must start 
with ‘shell’. 


Interprocess Communication 


Event channels are used for communication between processes. The root process and 
the selector shell expect information from their son processes through a 
SYS_SON_TERM event channel, telling why the son terminated, and whether the father 
sheuld restart the sen, select or start another shell, turn the power off, or restart the 
machine. The OS guarantees that this event will always be sent back to the father of 
a terminated process via the local event channel, even if the son process was 
unwillingly aborted. 


At Shell Startup 


FATHER: A process that starts a shell must do the following: 


1) Establish a local event channel to allow its son to communicate with it 
(OPEN_EVENT_CHIN). 


2) Stert the son shell (MAKE_PROCESS). 
3) Wait for a SYS_SON_TERM event (WAIT_EVENT_CHN). 
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SON: The shell that was started must do the fallowing: 
1) Declare a SYS_TERMINATE exception handler (DECLARE_EXCEP_HDL). 


This exception will be signalled when the shell process is about to be 
terminated for any reason: because KILL_PROCESS or TERMINATE_PROCESS 
has been called; because the process ran to completion, because there has 
been a bus error, address error, illegal instruction, privilege violation, or line 
1010 or 1111 emulator error. 


If this procedure is declared, the OS will a/ways give it a chance to run 
before the process is terminated. 


It is recommended that new sheils not assume anything about the state of the 
machine (e.g. the console setting, etc.). 


For more information on event channels and on starting up other processes from 4 
shell, refer ta the Qperating Systern Reference Manual 


FR Shell Termination 


SON: It is the shell's responsibility to make the operating systern call to 
TERMINATE_ PROCESS to open an event channel, s_eventblk (an array of longints). 
The first entry of this block (s_eventblk{1] ) contains the event that tells the shell's 
father what to do. The chosen meanings for these values are: 


1--Restert same shell (shell crashed and needs ta be restartea). To avoid infinite 
loops of START - CRASH - RESTART - CRASH..., the user will be able to 
intervene when the selector shell] is reached. . 


2--Select another shell (SELECT_ANOTHER cornmand). 


3--Start the specified shell. The remaining longints in the event text block 
(s_eventblK{2_9] ) are interpreted as a packed array [1..32] cf characters (with 
no length field), containing the file name of the shell to es started. The 
unused portion of the array is packed with spaces. 


4--Turn machine off (white power button clicked, or POWER_GFF commian). 
3--Reboot the machine. 
other -- Unspecified. 


It will be the job of the shell's terminate exception hendler (which is just a procedure 
the shell owns) to guarantee that the proper SYS _SON_TEPRM event text is set before 
the shell actually terminates. It can do this by calling TERMINATE_PROCESS, one of 
whose parameters is a pointer to this black. 
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FATHER: The father of the shell that just terminated should: 


1} Reawaken because it has received the SYS_SON TERM event via its local 
event channel. 


2) Check the event text to see what to do. 


Examples 


Following are code segments from both a father shell and a son shell showing the 
start-up and termination of the son. 


These constant and type definitions are used throughout the following examples: 


CONST 
aRestert = 1; {Restart me } 
eSelectanather = 2; {Select another shell 3 
astertAnother = 3; {Start the shell nened in the event text } 
aOff = 4; {Turn off Lisa) 
eset = 5; {Reset the machine } 
TYPE 


{ this is a variant record which allows us to address the packed array of char } 
trix = RECORO CASE BOULEAN OF 
TRUE : CevOlk: $_eventolk); 
FALSE: (zeroth: Tongint; 
first: longirt; 
_ rest: packed orray (1. .Rax: carne of char: ): 
END: {trix} 


FATHER: This code shows & father shell starting up a son shell and waiting for its 
termination. 


PROCEDURE Shell Loop; 


VAR OSerr: integer; 
procIB: longint; 
fname: pathname; 
entry: names tring; 
nextToDo: integer; 
_- @X_ Name: t_ex_nane; 
. @Vv_chan_refnum: integer; - 
 @V ch _name: pathname; ts 
WeitList: t_waitlist; 
ev_ptr: r_eventblk; 


PROCEDURE SelectShell (VAR fame: pathnene); 
BEGIN 

WRITEC'Next Shell 7°); 

READLNC fname >; 
END; (SelectSnell} 
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PROCEDURE Stuf fName(ev_bilk: 5_eventblk; VAR fneme: pathname); 
WAR Dlock: trix; 
i: INTEGER; 
BEGIN 
block .evb1k <= ev_blk; 
1 := 1; 
fname := '': (null string} 
WHILE i¢s32. DO BEGIN 
IF fneme{i)=' ' {space} THEN BEGIN 
fneme(Q) := chrci-1); {stuff length field} 
EXIT (Stuf fame); 
END: {IF} 
frameli] := Dleck.rest{i): 
2:21 +44; 
END; {WHILE} 
fneme[O}) := chr(32); {stuff length field) 
END; {Stuf fName) 


BEGIN (Shel 1Loop} 


Open_Event_Cnncoserr ,ev_ch_neme, ev_chan_re fnum, ex_name, receive); 
SelectSMnell ¢ fname >; 


REPEAT 
Make Process (osErr, prociD, fname, entry, ev_chen_refnum): 
IF (GsErr <= 0) THEN ane N 
waitList.length := 
waitList. ble = ev_chen_refnun; 
Wei t_Event_Chn(oserr, iwai TList,wnich, @v_ptr); 


{code for father shell bringing down son starts here} 
Kill Process (osEry, proc!b); 


IF ev_ ptr .event _text{[O}cel) term THEN {called terminate_process } 
NextToDo := ev_ptr.event_text[1) 
ELSE 


NextTodo <= aSelectanother; 
END: (made the process success fully} 


CASE NextToDo OF 
aRestart: {do nothing): 
aSelectanother: SelectShell ( fnene); 
eStartanother: Stuf fName(ev_ptr .event_text, frame); {get nene of Nex*Shel! out of event_text} 
aff: MwutDowcadff);: (a-- turn the machine off} 
eReset: SnutDown(eReset); (5--reset the machine} 

OTHERWISE SelectSell; 

END; {case NextToDo) 


UNTIL Hel lFreezesOver; 
END; (Shell Loop} 
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SON: This procedure makes the necessary calls for the start-up of a shell. 


PROCEDURE Shellinit: 
VAR OSerr: INTEGER; 
PInfo: ProcinfoRec: 


BEGIN 
info_process(OSerr , My_ID, PInfo); 
IF Pinvo.father_ID = 1 {root} THEN BEGIN 
BlockICinit; phe PPasLiDc} 


PMinit; {from PNM} 
pee IF oe THEN Sethtiikey(33); {Stenderd NMI keycep} 
> {IF} 


END; (Shellinit) 


This code shows the shutdown of a shell. If the ShutDown procedure is declared as 
the Sys_Terminate exception handler, it will properly communicate to its father its 
reason for terminating. 


PROCEDURE Shutdown (why: INTEGER); 
TYPE 


VAR 
block: trix; ( the variant recoyd } 
Oe eae e_neme: 
: INTEGER; { for the for loop } 
Qserr: INTEGER; { required parameter for the call to terminate_process } 
BEGIN 
ees evolk({1] 


F why = eSter tinisone THEN BEGIN 

NextShe}] := ‘shell .next'; . 

{copy string without length field) 

FOR 1 := i TO lengthcnex 11} DO block.rest[{i] := nextsnel1[i }; 
ee FOR i := length(nextsnell> + 1 TO Max_ename 00 block. rest(ij :=' '; 
terminate_process(0Serr , 2] ock .evtlk); 

ENO; (StutDown} 
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**#fyerns from Fred's memo 4—23-G4*** 


Summary 


The Workshop's file manager has been extended to take advantage of some new 
features provided by the 0S — password protection and hierarchical catalog 
structures. The file manager has been beefed up to allow convenient 
copy/backup/transfers onto more than one diskette (a more frequent occurance with 
Sonys) . 


The Details 
File Manager 


Changes to the File manager have revolved around three issues: the new OS 
hierarchical catalog structures, password protection, and backup to multiple 
volumes. 


Following are details on how the various File Manager commands have changed. 


o 6dddCatalog command. The AddCatalog cornmand allows you to create new 
catalogs. The pathname you specify for a catalog should refer to a volume 
which has been initalized with the new OS's B-tree file systern structures. A 
catalog specified by a pathname without a volume part will be created with 
respect to the current main prefix. 


The dash is the catalog delimiter, so a file name referring to a file in a 
catalog right look like "-vol-cat-file" or "~vol-cati-cat2-file", and so on. A 
file name of the form "cat-file” is interpreted relative to the current prefix 
and thus might refer to "-val-cat-file"” or "-vol-catl-cat-file" depending on 
whether the current prefix was set to a volurne or to a catalog. 


There is no special command to put a file in a catalog. Once 6 catalog has 
been created, newly created files will get put into it in two ways: (1) if the 
new file's narne is specified by a full pathnarne with volurme and catalog parts, 
in which case the file is put in the specified catalog (which must exist before 
a file can be put into it); and (2) if the new file's narne does not have a 
volume pert (i.e., it is a partial pathname) and the current prefix is to a 
catalog, in which case the file is created in the currert catalog (or the 
appropriate sub-catalog if the new file's pathname includes a catalog part). 


Note that when the OS tries to find a file given a partial pathname, the file 
will be found only if (1) the pathname has no catalog part and is located in 
the current prefix volurne or catalog, or (2) if the pathnarne has a catalog part 
that corresponds to 4 path starting with a catalog at the top level in the 
current prefix volurne or catalog. 


0 Backup/Copy/Transfer to multiple diskettes. The Backup, Copy and Transfer 
commands share a common file duplication mechanism that has been modified 
to allow backups (or whatever) to mutilple volurnes. If a list of files is being 
copied to a diskette and you run out of space, you will be told what file didn't 
fit and how rnany more blocks were needed, and you will be asked whether you 
want to continue on another diskette. If you answer Yes you will be lead 
through @ diskette change and the operation will continue. Note that the 
volume nares of the subsequent disks need not match the first, even if the 
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original destination was specified with a particuler volume name as opposed to 
a generic device name. 


o List and Names commands. Two new attributes are indicated for items in the 
List command display. The D attribute indicates a directory (C for catalog 
would have been nicer but was already in use for closed-by-OS) and the * 
attribute indicates a password protected file (see the next section). 


The List and Names commands will now indent names to show the catalog 
structure when listing B-Tree catalogs. The one exception ta this case is 
when you do a “non-contiguous” or partial list, that is, when you use 4@ 
wildcard specification with something to match following the wildcard 
character, causing only some of a contiguous subset of files to be listed. A 
wildcard specification of the form "<left pattern><wildcard char>" will select a 
"contiguous" subset of files matching <left pattern>, while a wildcard pattern 
of the form “<left pattern><wildcard char><right pattern>" will select only 
some of the set of files matching <left pattern>, resulting in a list with any 
number of discontinuities. Since a partial list is not assured of containing 
enough files to indicate the catalog hierarchy via indentation, the List and 
Names commands will print an unindented list of compiete pathnames 
matching the wildcard specification. 


NOTE: In the past the Workshop has truncated file names in the displays of 
several cornmands (such as the List cormmand which has 4 limited field in 
which to print the name, and commands like Copy which display "<source file> 
copied to <destination file>"). In some cases the narnes would be simply 
truncated and in others the last two characters would be replaced with two 
periods. The new Workshop should now indicate truncation by replacing the 
last character displayed with "..." (i.e. the ellipses character). 


0 Prefix command. Catalogs have changed the prefix command so that prefixes 
may now be to arbitrary catalogs in addition to volumes. Prefixes rnust be 
specified with complete pathnarmes; that is, if you are prefixing to a 
subcatalog, you must specify the complete path to the catalog. 


The effect of the current prefix on the interpretation of file names was 
discussed in the previous section. 


WARNING: Due to 4 recent change in the OS, the act of setting the main 
prefix (or working directory) has greater consequences than it used to. In 
particular, it may cause problems in running programs which use intrinsic units 
(this includes all the Workshop tools). The OS loader used to load a program's 
intrinsic libraries from the boot volume using the library names in 
INTRINSIC.LIB (which it makes a copy of at boot tirne). The library narnes 
used to be partial pathnames without a volume specification. Now the OS 
loader tries to find the libraries according to the pathnames it found in 
INTRINSIC.LIB, which means it will look on the prefix volume (or catalog) if 
the names in INTRINSIC.LIB were partial pathnames. There are two solutions 
to this problem: (1) copy the intrinsic.libraries to the prefix catalog, which 
could result in a proliferation of library files, or (2) change the names of the 
libraries in INTRINSIC.LIB to pathnares of the form "-#BOOT-libnarne”, and 
then reboot so that the OS will cache the new names. The latter solutian is 
the best in general, but requires tarnpering with INTRINSIC.LIB (which makes 
many people nervous, so I've written an exec file to do it ... see me if you're 
interested). The first solution points out the flexibility of the new scheme, 
that is, you may support several different library environments on the same 
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volurne via prefixing. 


o AddPassword and RemovePassword commands. The two new commands 
supporting password protection sre found under the FileAttributes cornrnand. 
AddPassword allows you to password protect a file (or files via wildcards). 
Don't forget the password! RernovePassword allows you to remove passwords 
from files, but you must know the password to remove it. 


A key point to note about password protected files in the Workshop is that the 
Workshop tools will not be able to open a file once it is password protected, 
SO passwords rnust be rernoved to make the files useable. Admittedly this is a 
less-than-optirnal password protection scheme, but short of a major redesign 
of the file access methods of the Workshop and all its tools, it does provide 
reasonable protection at little expense. 


o Initialize command (the new file system) Although this command has not 
changed, it is useful to note that volumes initialized under the new Workshop 
and OS have a new structure (B-trees) which allows for hierarchical catalogs. 
Since these structures cannot be applied retroactively to old volumes, a device 
must be reinitialized in order to take adavantage of these features. 


The following fact may be of interest to speed freaks and Priam users. Since 
the names in a B-tree catalog are already sorted, the shell knows enough to 
not sort the files coring from B-tree volumes when performing file manager 
commands which operate on lists of files. This means, for example, that 
running the List cornmand on a reinitialized Priam should be much faster than 
before, since the potentially very large list of files does not need to be sorted. 
Incidentally, the bubble sort of days of yore has been replaced with 4 Shell 
sort (aptly enough), which is many times faster, so life should be greatly 
improved even if you don't reinitialize your Priam. 


Oo OnLine command. The OnLine cornmmand has changed in one irnmediately 
obvious way -- the new device names used by the new OS. For the sake of 
convenience (to make the device names intelligible to humans) the OnLine 
command has been altered to also display the old device names which the new 
OS supports as device aliases. The point to note is that the aliases are no 
longer the real device names, so while the new names and aliases are 
accepted going into the OS, only the new names corne back out. 


The OnLine command has been modified in another less obvious way. The 
prefix attribute (P) is now sometimes displayed in lower case (p). The 
uppercase P indicates that the main prefix is to the indicated volurne, while a 
lowercase p indicates that the prefix is to a catalog somewhere on that 
volume. . 


NOTE: It is possible to confuse the Online command into thinking that 
devices are configured that when they are not. A typical example is getting 
an error in the middle of the Online output which says that it could not find 
#11 (i.e, paraport) on a Pepsi. The problem is eliminated by using Preferences 
or the CDConfig program to detach the non-existant device. Similarly, instead 
of an error, you may find that the Workshop pauses unexpectedly in the middle 
of Online output. This problern is also caused by a device being configured 
but not present (the pause in the Online output is the device driver tirning out 
while trying to access the device). The point to note is that the Online 
command no longer iterates through 4 fixed list of devices as it did before: 
instead, it must rely on the information supplied by the Parameter Memory 
manager (which is set when you run Preferences). So make sure that 
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Preferences' idea of how the system is configured is correct! 


o File Selection. The File Manager uses a common mechanism for file selection 
for all of the comrnands which operate on lists of files (list, copy, delete, 
rename, etc.). Lists of files sre specified via wildcard patterns against which 
file names are matched. These wildcard patterns have the general form: 


<catalog part><left pattern><wildcard char><right pattern> 
Various combinations of the wildcard pattern elements can be ornitted. 


The wildcard characters are "?" and "=". These will now operate on all files in 
a B-tree catalog and on any files in subcatalogs, that is, the wildcard 
matching mechanism will "go down into" subcatalogs as it atternpts to find 
files satisfying the wildcard specification. New variants of "?" and "=" have 
been introduced to allow file selection to take place only on the top level of a 
B-tree catalog (without going into subcatalogs). The new variants are enabled 
by pressing the option key while typing "?' or "=", resulting in "é" or "#". 


Please note (from the general form of a wildcard pattern given above) that 
wildcards ere not permitted in the <catalog part> of a wildcard specification. 
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Apple Computer Inc. 


Macintosh Division 
Development Tools Clump 77? 


April 23, 1984 


TQ: Macintosh Software Engineering 
FROM: Fred Forsman 


SUBJECT: Workshop Enhancements for Spring Release 
(or what's new in the old shell geme) 


A number of enhancements to the Workshop Shell have been implemented for 
the Spring release. The next section summarizes the changes, and the 
remainder of the memo the details. 


Summary 


The Workshop's file manager has been extended to take advantage of some 
new features provided by the OS -- password protection and hierarchical 
catalog structures. The file manager has been beefed up to allow 
convenient copy/backup/transfers onto more than one diskette (a more 
frequent occurence vith Sonys). The resident process mechanism has been 
removed, having become obsolete with the new OS. A number of 
convenience features have been added, such as the remembering Run 
command. A unit has been provided for communication between programs 
and the shell or between cooperative programs. 


Last, but not least, the Exec File processor has been extended so that 
it now provides a fairly powerful interpretive language for controlling 
development scripts. The usefulness of the exec processor has been 
greatly enhanced by converting it from a preprocessor into a truly 
interactive processor, by allowing it to stay present while Workshop 
commands ere executed and programs are run so that the exec script can 
be resumed after the non-exec workshop commands have been executed. 
(Formerly all exec processing took place first and then the resulting 
script was run.) The exec language has been enhanced to include looping 
constructs, named variables, file I/O, a directory search capability, 
screen control functions, and functions to perform arithmetic 
operations. The performance has also be greatly improved, due in part 
to a new file caching mechanism. (A word of reassurance: your old exec 
files will work just as before, only faster.) 


The Details 


Note that the following description assurnes knowledge of the Release 1.0 
Workshop and Pepsi Workshop (virtually identical to 1.0 but with uated for 
the new hardware). 


Remembering Run Command 


The Run command will remember what you ran last and offer it as a 
default. Even if you don't always want to run the same thing again, 


~ 
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it serves as a convenient reminder of what you did last. 
Run commands in exec files will not be remembered. 
No More Resident Processes 


Improvements in the OS have obviated the need for the Workshop's 
old resident-process mechanism (which would allow certain specified 
processes to be suspended rather than killed so that they could be 
rerun with less swapping). 


As a result, the System manager's Process manager subsystem has 
been simplified by removing the commands to support the list of 
resident programs. (Note that the file LDS_RES PROCS.TEXT that 
once saved this list between invocations of the Workshop is no 
longer used.) The process manager is still useful for monitoring and 
killing suspended and background processes. 


Programs can still achieve the rnore interesting effects of residency 
(such as continuing from where they last were, as does the Mouse 
Editor) by suspending themselves. When the program is reinvoked, 
the shell will detect that a suspended instance of the process is still 
eround and will reactivate it. 


File Manager 


Changes to the File manager have revolved around three issues: the 
new OS hierarchical catalog structures, password protection, and 
backup to multiple volumes. 


NOTE: The discussion below assumes familiarity with the breakdown 
of pathnames into volume, catalog and filename components. The 
following examples of the various forms of valid pathnames should 
make the division into components clear. The possible forrns of 
pathnames before catalogs were two: 


-volname-filename { full pathname > 

filname { partial pathneme; no volume } 
The new forms of pathnames now possible with catalogs are: 

-~volname-catname-filename { full with catalog } 

~volname-catname—catname2-filename { full with catalogs } 

catname-filename { partial with catalog(s) } 


Following are details on how the various File manager commands 
have changed. 


0 File Selection. The File manager uses a common mechanism for 
file selection for all of the cormmands which operate on lists of 
files (list, copy, delete, rename, etc.). Lists of files are specified 
via wildcard patterns against which file names are matched. 
These wildcard patterns have the general form: 


<catalog part><left pattern><wildcard char><right pattern> 


Various combinations of the wildcard pattern elements can be 
omitted. 


The wildcard characters are "?’ and "=". These will now operate 
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on all files in a B-tree catalog and on any files in subcatalogs, 
that is, the wildcard matching mechanism will “go down into" 
subcatalogs as it attempts to find files satisfying the wildcard 
specification. New variants of "?" and "=" have been introduced 
to allow file selection to take place only on the top level of a 
B-tree catalog (without going into subcatalogs). The new variants 
are enabled by pressing the option key while typing "?' or "=", 
resulting in “é" or “e#". 


Please note (from the general form of a wildcard pattern given 
above) that wildcards are not permitted in the <catalog part> of a 
wildcard specification. 


o Initialize command (the new file system). Although this command 
has not changed, it is useful to note that volumes initialized 
under the new Workshop and OS have a new structure (B-trees) 
which allows for hierarchical catalogs. Since these structures 
cannot be applied retroactively to old volumes, a device must be 
reinitialized in order to take adavantage of these features. 


The following fact may be of interest to speed freaks and Priam 
users. Since the names in a B-tree catalog are already sorted, 
the shell knows enough to not sort the files coming from B-tree 
volumes when performing file manager commands which operate 
on lists of files. This means, for example, that running the List 
comrnand on & reinitialized Priam should be much faster than 
before, since the potentially very large list of files does not need 
to be sorted. Incidentally, the bubble sort of days of yore has 
been replaced with a Shell sort (aptly enough), which is many 
times faster, so life should be greatly improved even if you don't 
reinitialize your Priam. 


0 AddCatalog command. The AddCstalog command allows you to 
create new catalogs. The pathname you specify for a catalog 
should refer to a volume which has been initalized with the new 
OS's B-tree file system structures. A catalog specified by a 
pathname without a volume pert will be created with respect to 
the current main prefix. 


The dash is the catalog delimiter, so a file name referring to a 
file in a catalog might look like "-vol-cat-file" or 
"-vol-catl-cat2-file", and so on. A file name of the form 
"cat-file" is interpreted relative to the current prefix and thus 
might refer to “-vol-cat-file” or "-vol-cati-cat-file" depending on 
whether the current prefix was set to a volume or to a catalog. 


There is no special command to put a file in a catalog. Once a 
catalog has been created, newly created files will get put into it 
in two ways: (1) if the new file's name is specified by a full 
pathname with volume and catalog parts, in which case the file is 
put in the specified catalog (which must exist before a file can 
be put into it); and (2) if the new file's name does not have a 
volume part (i.e., it is a partial pathname) and the current prefix 
is to a catalog, in which case the file is created in the currert 
catalog (or the appropriate sub-catalog if the new file's pathname 
includes a catalog part). 
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Note that when the OS tries to find a file given a partial 
pathname, the file will be found only if (1) the pathname has no 
catalog part and is located in the current prefix volume or 
catalog, or (2) if the pathname has a catalog part that 
corresponds to a path starting with a catalog at the top level in 
the current prefix volume or catalog. 


o Prefix command. Catalogs have changed the prefix command so 
that prefixes may now be to arbitrary catalogs in addition to 
volumes. Prefixes must be specified with complete pathnames; 
that is, if you are prefixing to a subcatalog, you must specify the 
complete path to the catalog. 


The effect of the current prefix on the interpretation of file 
names was discussed in the previous section. 


WARNING: Due to 4 recent change in the OS, the act of setting 
the main prefix (or working directory) has greater consequences 
than it used to. In particular, it may cause problems in running 
programs with use intrinsic units (this includes all the Workshop 
tools). The OS loader used to load a program's intrinsic libraries 
from the boot volurne using the library names in INTRINSIC.LIB 
(which it makes a copy of at boot time). The library names used 
to be partial pathnames without a volume specification. Now the 
OS loader tries to find the libraries according to the pathnames it 
found in INTRINSIC.LIB, which means it will look on the prefix 
volume (or catalog) if the names in INTRINSIC.LIB were partial 
pathnames. There sre two solutions to this problem: (1) copy the 
intrinsic.libraries to the prefix catalog, which could result in a 
proliferation of library files, or (2) change the names of the 
libraries in INTRINSIC.LIB to pathnames of the form 
"-#BOOT-libname", and then reboot so that the OS will cache the 
new names. The latter solution is the best in general, but 
requires tampering with INTRINSIC.LIB (which makes many people 
nervous, so I've written an exec file to do it ... see me if you're 
interested). The first solution points out the flexibility of the 
new scheme, that is, you may support several different library 
environments on the same volume via prefixing. 


o OnLine command. The OnLine command hes changed in one 
immediately obvious way -- the new device names used by the 
new OS. For the sake of convenience (to make the device names 
irtelligible to humans) the OnLine command has been altered to 
also display the old device names which the new OS supports as 
device aliases. The point to note is that the aliases are no 
longer the real device names, so while the new names and aliases 
are accepted going into the OS, only the new names come back 
out. | 


The OnLine command has been modified in another less obvious 
way. The prefix attribute (P) is now sometimes displayed in 
lower case (p). The uppercase P indicates that the main prefix is 
to the indicated volume, while a lowercase p indicates that the 
prefix is to a catalog somewhere on that volume. 


NOTE: It is possible to confuse the Online command into 
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thinking that devices are configured that when they are not. A 
typical example is getting an error in the middle of the Online 
output which says that it could not find #11 (i.e., paraport) on a 
Pepsi. The problem is eliminated by using Preferences or the 
CDConfig program to detach the non-existant device. Similarly, 
instead of an error, you may find that the Workshop pauses 
unexpectedly in the middle of Online output. This problem is 
also caused by a device being configured but not present (the 
pause in the Online output is the device driver timing out while 
trying to access the device). The point to note is that the Online 
command no longer iterates through a fixed list of devices as it 
did before; instead, it must rely on the information supplied by 
the Parameter Memory manager (which is set when you run 
Preferences). So make sure that Preferences’ idea of how the 
system is configured is correct! 


o List and Names commands. Two new attributes are indicated for 
items in the List command display. The D attribute indicates a 
directory (C for catalog would have been nicer but was already in 
use for closed-by-OS) and the * attribute ngicetes & password 
protected file (see the next section). 


The List and Names commands will now indent names to show 
the catalog structure when listing B-Tree catalogs. The one 
exception to this case is when you do a “non-contiguous” or 
pertial list, that is, when you use a wildcard specification with 
something to match following the wildcard character, causing only 
some of a contiguous subset of files to be listed. A wildcard 
specification of the form "<left pattern><wildcard char>" will 
select a "contiguous" subset of files matching <left pattern>, 
while a wildcard pattern of the form “<left pattern><wildcard 
cher><right pattern>" will select only some of the set of files 
matching <left pattern>, resulting in a list with any number of 
discontinuities. Since a pertial list is not assured of containing 
enough files to indicate the catalog hierarchy via indentation, the 
List and Names commands will print an unindented list of 
complete pathnames matching the wildcard specification. 


NOTE: In the past the Workshop has truncated file names in the 
displays of several commands (such as the List command which 
has a limited field in which to print the name, and commands 
like Copy which display "<source file> copied to <destination 
file>"). In some cases the names would be simply truncated and 
in others the last two characters would be replaced with two 
periods. The new Workshop should now indicate truncation by 
replacing the last character displayed with "..." (i.e., the ellipses 
character). 


0 AddPassward and RemovePassword commands. The two new 
commands supporting password protection are found under the 
FileAttributes command. AddPassword allows you to password 
protect a file (or files via wildcards). Don't forget the password! 
RemovePassword allows you to remove passwords from files, but 
you must know the password to remove it. 


A key point to note about password protected files in the 
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Workshop is that the Workshop tools will not be able to open a 
file once it is password protected, so passwords must be removed 
to make the files useable. Admittedly this is a less-than-optimal 
password protection scheme, but short of a major redesign of the 
file access methods of the Workshop and all its tools, it does 
provide reasonable protection at little expense. 


0 Delete Command Those of you who look closely at the behavior 
of the Delete command operating on B-tree catalogs may notice 
anew wrinkle in the command's operation. While all the other 
File manager commands perform their operations on an 
alphabetically sorted list of files, the Delete command must 
delay the deletions of catalogs which are not yet empty. Thus 
the Delete commands works in two passes: in the first pass all 
files are deleted in alphabetical] order, as are catalogs which are 
empty; in the second pass, any catalogs not deleted in the first 
pass are now deleted in reverse alphabetical order (to take care 
of catalogs contained in other catalogs). 


o Backup/Copy/Transfer to multiple diskettes. The Backup, Copy 
and Transfer commands share a common file duplication 
mechanism that has been modified to allow backups (or whatever) 
to mutilple volumes. If a list of files is being copied to a 
diskette and you run out of space, you will be told what file 
didn't fit and how many more blocks were needed, and you will 
be asked whether you want to continue on another diskette. If 
you answer Yes you will be lead through a diskette change and 
the operation will continue. Note that the volume names of the 
subsequent disks need not match the first, even if the original 
destination was specified with a particuler volume name as 
opposed to a generic device name. 


Program—Shell Communication 


An intrinsic unit (ProgComm) has been added to SULib which allows 
programs to communicete with the shell and with other programs. 
Three basic mechanisms are provided. 


o Set Next Run Command A programmatic call is provided which 
allows & program to tell the Workshop shell what to run next. 
The specified program will be run next (after the current program 
is done), taking precedence even over an exec file in progress. 


0 The Program Return String. A string is provided which can be 
set prograrnmatically and which can be accessed from the exec 
processor (via the RETSTR function). This allows exec scripts to 
be written which make choices based on program results. 


0 The Communication Buffer. A 1K byte buffer (global to the 
Workshop) has been provided for communication between 
programs. The buffer can be used in any number of ways; 
however, a set of primitives supporting character and 
line-orierted I/O to and from the buffer is provided. 


More detailed information of the program communication unit can be 
found in the ProgComm appendix to this document. 


Note that the above mechanisms can be used in conjunction with 


Fred Forsman April 23, 1984 


Spring Workshop Shell Enhancements Page 7 


each other. For example, a program could write a series of 
invocation arguments to the communication buffer and then tell the 
shell to run a particular program next (via the set-next-run 
command). That program could then know to check the 
communication buffer to find its arguments. (In general, programs 
might be written so that they check the communication buffer for 
their arguments first and prompt for arguments from the console 
only if the arguments sre not found in the buffer). 


ProgComm's program-program communication facility has been used 
by several of the Spring release Workshop tools: 


o Compiler-—Generator communication. The Pascal compiler will 
now automatically invoke the Generator to perform the second 
step of the compilation process. This behavior can be suppressed 
by specifying the "$G-" option in response to the compiler input 
prompt. The third compiler prompt is now for a .OBJ output file 
rather than a .] output file (although a .1 is generated when the 
generator is called automatically). 


NOTE: The above change will probably mean that you will have 
to change your "Compile" exec file (either to eliminate the 
generate step or to use the $G- option). If you haven't been 
using a common compile exec file, then you probably have more 
editing in store. 


o Compiler-Editor communication. The compiler now provides the 
option of going to the editor in the event of a compilation error 
(the choices offered by the error prompt are SPACE to continue, 
CLEAR to escape, and E to go to the editor). If you go to the 
editor the point of error will be displayed in the appropriate 
source file and the compiler error message will be displayed. 


Exec Files 


Major extensions have been made to the Exec File processor, as 
enumerated below: 


0 Alternate "$" corvention. Now that the exec command 
language is filling out, you can create meaningful exec 
files with many more exec command lines than workshop 
(non-exec) command lines. Up until now these two types of 
lines have been distinguished by a "$" as the first 
significant character of exec lines. As @ consequence, exec 
files consisting of mostly exec command lines become 
unreadable or annoying with all of the dollar signs, which 
is unfortunate since the dollar signs mess up the lines 
which are inherently more readable and intelligible. 


Now exec files which begin with “EXEC” rather than "$ EXEC” 
will be accepted and processed with the "$" convention 
reversed, that is, workshop lines would then begin with a 
dollar and exec lines would not. This makes exec files 
consisting of mainly exec commands look more normal and 
readable, and in no way affects files written using the 
other convention. In fact the two conventions can be mixed, 
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that is, a file written in one convention can call a file 
written in the other convention. In the new convention, 
workshop lines begin immediately following the "$" (although 
leading and trailing blanks will be removed unless the "B" 
option is in effect). 


o Nemed parameters and variables. Nemes can now be associated 
with the %n variables, allowing meaningful nemes to be used 
to make exec files more readable and intelligible. 
Parameters can still be referred to in the old “%n" fashion, 
or they can be referred to with new nemes, or both. The 
names are declared (associated positionally with the “%n” 
paremeters) by having an optional parenthesized list of 
nemes on the exec command line, as in 


EXEC (volNeme, fileName) 
IF UPPERCASE (volNeme) = '-PARAPORT' THEN 
<etc.> 

ENDEXEC 


The paremeter names as specified on the EXEC command line 
must begin with an alphabetic character, may include 
subsequent alphabetic and numeric characters, and may be as 
long as you like, although only the first eight characters 
are significant (as in Pascal). The parameter list is not 
allowed to have "holes" in it, that is, you cannot do 
something like: 


EXEC (pNemeO, . pName2) 


Once the names are declared on the EXEC line, nemed 
paremeters can then be used as you would expect in exec 
lines (see "“volNeme" in the second line of the example 
above). In workshop (non-exec) lines the name should be 
Surrounded by square braces so that it can be distinguished 
from the surrounding text as in: 


EXEC (file) 
$F {filer }D{delete} [file] 
$Y {yes}O{Quit} 
<etc.> 

ENDEXEC 


The rule is that square braces are required to offset a 
paremeter name in contexts where processing is done in a 
text-oriented mode (i.e., when in workshop as opposed to 
exec lines). Otherwise, the nemes cannot cannot be 
distinguished (from the exec processor's point of view) from 
the text in which they appear. Note that [...] constructs 
in non-exec lines will be copied into the temporary file as 
is if the stuff between the braces is not recognized as a 
parameter name. 


Symbolic nemes must also be enclosed in square braces in 
order to be recognized in SUBMIT commands and in function 
calls. This is required since SUBMIT and function arguments 
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lists are scanned as if the arguments were pure text instead 
of string expressions. (This form of argument scanning was chosen to be 
Compatible with the scanning of arguments on the exec invocation line. 

Unfor tunately, this is one area that cannot be cleaned up without bresking 
everyone’ $ exec files, or else by introducing alternate versions of SUBMIT end 
function calls that take string expression arguments.» The following 
exemple demonstrates situations in which a name does and 


does not need to be enclosed in square braces. 


EXEC (file) 
$F {filer }C{copy} [file] 
$-l ower-backup/[file] { name with braces } 
IF file <> '' THEN { name without braces } 
SUBMIT compile ([file]) { name with braces } 
<etc.> 
ENDEXEC 


The scope of names is the body of the defining exec file. 
Up-level name references are not allowed, that is, neme 
references are always local (as they were before). 


o WHILE and REPEAT commands. These commands allow for 
repetition of command sequences under the control of an 
arbitrary boolean condition. The syntax for the WHILE 
command is as follows: 


WHILE <boolean expr> DO 
«arbitrary stuff> 
ENOWHILE 


The behavior of the WHILE construct is the same as the 
comparable Pascal construct. The <boolean expr> may be a 
condition of arbitrary complexity. The <arbitrary stuff> 
between the WHILE and the ENDOWHILE may be anything: exec 
commands (including nested WHILEs) or Workshop command 
lines. 


Similarly, the REPEAT command syntax is: 


REPEAT 
«arbitrary stuff> 
UNTIL <boolean expr> 


o RESETCAT command and NEXTFILE function. These allow an 
exec file to get files from an OS directory (based on a 
wildcard pattern if desired). These new constructs are 
illustrated in the following example: 


EXEC (file) 
RESETCAT '-paraport-=.text' 
REPEAT 
SET file TO NEXTFILE 
<what ever> 
UNTIL file = '' 
ENDEXEC 


For those of you femiliar with the OS calls, RESETCAT is 
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comparable to RESET_CATALOG and NEXTFILE is comparable to 
GET_NEXT_ENTRY. The RESETCAT command takes a <string 
expression> argument which specifies the directory and the 
search pattern (if any). If a fileneme part is specified in 
addition to a volume neme, the fileneme part will be used as 
@ search pattern for subsequent calls to the NEXTFILE 
function. If the wildcard character (=) is present standard 
wildcard matching takes place. If there is a filename part 
but no wildcard, the file name part is used as & search 
prefix (that is, "RESETCAT ‘foo'" is equivalent to "RESETCAT 
‘fooz'"). The NEXTFILE function returns an empty string 
when there sre no more entries in the directory. The 
RESETCAT command also has the side effect of setting the 
value of the IORESULT function described below. 


o JORESULT function. This works in conjunction with the 
RESETCAT command and the NEXTFILE function, indicating 
whether an error occured in the operation (similar to the 
IORESULT function in Pascal). IORESULT returns the empty 
string if no error occurred in the last significant 
operation (RESETCAT, NEXTFILE, OPENIN, OPENOUT). If an 
error occured, then a string with the error number, and the 
appropriate textual message is returned. An exemple: 


EXEC (dir, io€rr) 
REPEAT 
REQUEST dir WITH ‘Search what directory ?' 


RESETCAT dir 

IF IORESULT = '' THEN { successful RESETCAT } 
«search directory, etc.> 

ELSE { unsuccessful RESETCAT } 


SET ioErr TO IORESULT 
WRITELN ‘Bad directory specification’ 
WRITELN ‘OS error: ', io&rr 
ENDIF 
UNTIL FALSE 
<etc.> 
Cc 


0 HALT and ABORT commands. These commands stop the exec 
processor; the difference between HALT and ABORT is whether 
any accumlated Workshop commands will be processed. The 
HALT command will stop exec processing and will execute the 
commands that have been sent so far to the intermediate 
file. The ABORT command will stop exec processing and will 
not execute any accumlated commands. In a nut shell, if 
something really goes wrong you probably want to ABORT; if 
you have valid commands generated but not executed and you 
want to stop exec processing but still execute the queued 
commands, you probably want to HALT. 


Both commands take an optional "string expression" argunent 
which will be printed to the console (replacing an "Exec 
processing aborted." message in the case of the ABORT 
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command) . 


o EVAL function and numeric expressions. The EVAL function is 
used to evaluate arithmetic expressions, returning a string 
containing the result of the evaluation. While the exec 
language still deals only with objects which are strings, 
this feature introduces the capability of dealing with a 
string as a number. The syntax of the EVAL function is 


EVAL ( <numeric expression) ) 


where <numeric expression> is your usual arithmetic 
expression allowing the +, -, *, 7 MOD and (...) operators. 
The numeric elements can be supplied via unquoted numeric 
constants (decimal only), parameters or variables (with 
string values which must be numeric constants), string 
functions returning numeric string values, or functions 
which return numeric string values such as LENGTH, ORD, and 
POS. 


It is important to keep in mind the differences between 
numeric and string expressions. You should also be aware of 
the contexts in which each is required. For example, you 
should understand why "EVAL(1)" is valid and "EVAL('1') is 
not. 


Observe that the result type of the EVAL function is 4 
string (not a number, not a numeric string, just a string). 
The point to keep in mind is that all data objects in the 
exec processor are still strings. Only within the context 
of a <numeric expression» ere strings treated as numbers. 


Arithmetic is done with LONGINTs with no overflow detection 
except when numeric constants sre too large. 


Following is an exemple of a loop using a counter: 


SET N TO ‘O'{note 0 is expressed as a string constant} 
WHILE N <> ‘10° 

<what ever > 

SET N TO EVAL (N + 1) 
ENDWHILE 


o Mare string functions: LENGTH, COPY, POS, LOWERCASE, CR, 
and ORD. A number of new string funtions have been added. 
Some of these take advantage of the numeric expression 
capability introduced by the EVAL function. Note that some 
of the functions may be used in numeric expressions (since 
they return strings with numbers) in addition to string 
expressions. 


LENGTH ( <str expr) ) 
LENGTH takes a string expression argument and returns a 
string with a number in it. LENGTH may be used in both 
string and numeric expressions. 
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COPY ( <str expr>, <num expr), <num expr) ) 
COPY takes three arguments: a string expression and two 
numeric expressions. It returns the appropriate substring 
of the first argument, as in PASCAL with the exception that 
if the third argument is too large it will return what is 
available rather than the empty string. COPY can be used in 
string expressions but not numeric expressions (since it 
typically does not return a number). Keep in mind the 
differences between the two types of arguments taken by the 
copy function — string and numeric expressions. An 
exemple: 


EXEC (foo, n, ch) 
SET n TO LENGTH(foo) 
SET ch to COPY(foo, 1, 1) {ch := first char of foo} 
SET foo TO COPY(foo0,n/2,n) {foo := last half of foo} 
<etc.> 


POS ( <str expr), <str expr) ) 
POS takes two string expression arguments, and returns 4 
string with a number in it. The number is the position of 
the first occurrance of the first string within the second. 
If the first string does not appear in the second '0' is 
returned. POS may be used in both string and numeric 
expressions. 


LOWERCASE ( <str expr> ) 
LOWERCASE takes @ single string expression argument and 
returns that string lowercased. We have UPPERCASE already 
so it seemed only fair to give equal time to lowercase. 


CHR ( (num expr) ) 
CHR takes a numeric expression and returns & one-character 
string with the character value corresponding to the numeric 
value MOD 255. 


ORD ( <str expr) ) 
ORD takes a string expression argument. An exec-time error 
will be generated if the string does not have a length of 
one. ORD returns a string with a number representing the 
integer value of the character. ORD may be used in both 
string and numeric expressions. 


Oo New string comparison operators. Previously only the = and 
<> string comparison operators were supported. To this the 
», <«, >s, and <= operators have been added. These all 
function in the expected way. Now for the confusing pert. 
Since the EVAL function has introduced strings which 
function as numbers, we need operators which compare strings 
as if they were numbers (instead of as strings). The new 
numerical string compare operators ere EQ, NE, LT, GT, LE, 
and GE. For exemple, try comparing 9 and 16 with the 
following exec procedure. ; 


EXEC (nl, n2) 
IF ni > n2 THEN 
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WRITELN n1,' is alphabetically greater than ',n2 


WRITELN n1,' is not alphabetically greater than ',n2 
ENDIF 
IF ni GT n2 THEN 
WRITELN ni, ' is numerically greater than ',n2 
ELSE 
WRITELN ni,' is not numerically greater than 
ENDIF 
ENDEXEC 


,n2 


o TRUE and FALSE constants in boolean expressions. Just as 
you would expect. Useful for "WHILE TRUE DO” and similar 
constructs. 


o Screen contro] commands: GOTOXY, CLEAR and CURSOR. A number 
of comnands have been added to allow screen-oriented exec 
procedures 


GOTOXY <num expr>, <num expr> 
GOTOXY takes two numeric expression arguments separated by a 
comma. The behavior is the same as Pascal's GOTOXY. Values 
which are beyond the upper or lower limits for coordinates 
will peg at the limit. 


CLEAR <clear option> 
CLEAR takes a <clear option» (SCREEN, ENOSCREEN, and 
ENDLINE) as an argument. SCREEN will clear the screen and 
leave the cursor at <0,0>. ENDSCREEN will clear to the end 
of the screen from the current cursor position. ENDLINE 
will clear to the end of the line from the current cursor 
position. 


CURSOR <cursor option» [ <num expr> ] 

— CURSOR takes a <cursor option») (HOME, UP, DOWN, RIGHT, LEFT) 
as an argument, followed by an optional numeric expression. 
The results of the various cursor options should be obvious, 
and the optinal numeric expression can be used to supply a 
repetition count. 


o File I/O: RESET, REWRITE, and CLOSE commands. The current 
READs and WRITES have been extended to work with files in 
addition to the console. In order to support this new 
functionality three new commands have been introduced for 
opening and closing files. Note that these file-oriented 
commands work only on text files. 


RESET <id> , <str expr> 
RESET opens a file for input. An <id> (an identifier, as in 
Pascal, with only the first eight characters being 
significant) is used to establish a file variable (which is 
used to identify the file for subsequent reads, writes, and 
Closes). The RESET command serves as @ dynemic declaration 
of the file variable which becomes known globally for the 
duration of exec processing or until the file is CLOSEd. 
The string expression argument is used’ to specify the 
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pathname for the file. The value of the IOGRESULT function 
will be set appropriately after the operation. 


REWRITE <id> , <str expr> 
REWRITE opens a file for output and is otherwise like the 
RESET command. 


CLOSE <id> 
CLOSE closes the file associated with the file variable, and 
causes the file variable to be deallocated. 


The READCH, READLN, WRITE, and WRITELN commands have been 
extended to deal with files by adding an optional file 
specifier. The form of the file specifier is: 


( <id ) 
where <id> is a file variable. The file specifier should 
follow the command keyword, preceeding the normal command 
arguments, as in the following exemples: 


READCH (inFile) Char 

READLN (inFile) Line 

WRITE (outFile) ‘This is a test: ‘, message, 
WRITELN (outFile) { write a CR } 


o IA to the ProgCom= Comsunication Buffer. The I/O commands 
defined in the previous section (REWRITE, RESET, CLOSE, 
READCH, READLN, WRITE, and WRITELN) can also be used to 
write to or read from the communications buffer provided by 
the ProgComm unit (see the appendix on ProgComm). There is 
@ predefined <id>) -- ‘CommBufr' — which serves as a4 
pseudo-file identifier for the communications buffer. With 
the exception of CLOSE, all of the I/0 commands are the seme 
are the seme as the file-oriented forms, as in the following 
exemples: 


RESET CommBufr, ‘key’ 

REWRITE CommBufr, ‘key’ 

READCH (CommBufr) Char 

READLN (CommBufr) Line 

WRITE (CommBufr) ‘This is a test: ', message, '.' 
WRITELN (CommBufr) { write a CR } 


Note that when openning the communication buffer, the second 
arguments of RESET and REWRITE are the access key instead of 
a file name. CLOSE is syntactically different in that it 
also requires a second argument specifying an access key, as 
in: 

CLOSE CommBufr, ‘key’ 


WARNING: CLOSE on the CommBufr has the effect of flushing 
the CommBufr. Consequently, CLOSE should not be called 
after writing to the CommBufr. It should be called after 
reading if the buffer is not intended to be read by somebody 
else, and it should be called when you want flush the 
buffer. Note that the CLOSE will only succeed if you 
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specify right key or if the buffer was not keyed, thus a 
CLOSE with a key is in effect a conditional flush of the 
buffer. An unconditional flush can be achieved with a 
REWRITE, which always clobbers the buffer, regardless of the 
key. 

o DOIT command. The DOIT command transforms the exec 
processor into more than just a preprocessor. When a DOIT 
is encountered all commands that have accumulated in the 
exec temporary file will be executed and then control will 
return to the current exec file following the DOIT (with the 
temporary file emptied). This allows you to execute 
Workshop commands and to run programs from an exec file and 
then to base further exec processing on the results of these 
commands. The concept is simple, yet powerful. A trivial 
exemple of something you could not do before is print a 
message after some workshop commands in an exec file have 
executed, as in: 


EXEC (fromVol, toVol) 
WRITELN ‘Now starting backup ...' 
$F {filer}B{backup} [fromV¥ol J-=, [toVol ]-$ 
$O{quit the filer} 
DOIT 


WRITELN ‘Backup of ', fromVol, ' to ', 
toVol, ‘' completed’ 
ENDEXEC 


One point to note about the DOIT command is that it causes 
immediate execution of what has accumulated in the temporary 
file, which you may find surprising initially if you are 
stepping through an exec file via the "S" option. As a 
result, the accumulated commands will be executed and then 
you will return to stepping following the DOIT. 


o RUN command. The RUN command allows a progrem to be run 
immediately from an exec file without affecting commands 
being accumulated in the temporary file. The simplest form 
of the RUN command is: 


RUN <str expr> 
where the <str expr) gives the pathneme of the program to 
Tun. Note the RUN exec command gets executed immediately at 


exec time, whereas an embedded Meek shop "R" command will get 
executed at run time. 


Since progrems often require input from the console, the 
following form of the RUN command is provided: 


RUN <str expr> INPUT 
<arbitrary stuff> 
ENDRUN 


Here the “stuff" between INPUT and ENDRUN is put into 
another temporary file to use as exec input while the 
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progrem is being run. This "stuff" will not affect any 
commands accumulating in the normal temporary file. If the 
progrem being run requires more input that provided by the 
"stuff", input will revert to the console to complete the 
progrem's input requirements. If too much "stuff" is 
provided, the excess will be ignored. 


0 The RETSTR function. The RETSTR function returns what is in. 
the ProgComm unit's return string. Thus a return string set 
by a progrem uSing the ProgComm unit can be accessed from an 
exec file. For exemple: 


EXEC 
RUN 'foo' 
IF RETSTR <> ‘SUCCESS' THEN 
ABORT ‘Foo failed’ 
ENDEXEC 


o The "G" invocation option. The "G" (or generate only) 
invocation option allows you to test out your exec files 
without actually running them. Note that the "G" option 
disables the DOIT and RUN commands. 


o The "E" invocation option. The "E" (or continue even with 
errors) invocation option allows you to run exec files which 
run workshop progrems which have errors which would normally 
stop exec file execution. When running under this option, 
run-time errors will not stop exec processing. In using 
this option you run a higher-than-normal risk of your exec 
file becoming out-of-synch and doing things you did not 
intend. But the option can be very useful if you must run 
test suites which contain errors. 


o The "K" invocation option (formerly "T"). The old "T” 
option, indicating that the generated temporary file should 
be saved rather than deleted after being run, has been 
renemed to "K" for Keep. This change was made because the 
new documentation for exec files (which will appear someday) 
does not refer to the generated file as a temporary file, so 
the "T" no longer makes any sense (not that it was a good 
choice for an option neme in the first place). 


Oo Improved performance and file caching. A file caching 
mechanism has been added to the exec processor. The cache 
currently consists of 5 pages (where a page is two blocks). 
The caching mechanism can cache 5 small files at at time 
where "small" is defined as having a listed size of 4 blocks 
(1 header page and 1 page of significant text). Small files 
will be put in the cache, and subsequent SUBMITs or function 
calls to that file will be read from the cache. The cache 
is maintained on a LRU (least recently used) basis.. This 
means, for example, that if you call a sub-exec file to 
compile many times from a build exec file, the compile exec 
file will typically only be read once. 


To further boost performance the exec processor's handling 
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of text files now goes through a unit developed by Ira Ruben 
(I0Primitives in SULib). 


These changes, along with numerous other tweaks to low-level 
routines in the exec processor, have resulted in more than 
doubling (sometimes tripling) of the exec processor's speed 
(although you may find the performance to be better or worse 
than this depending on road conditions and how your exec 
files are structured). 
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Appendix 1 
ProgComm: the Program Communication Unit 
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Summary 


An intrinsic unit (ProgComm) hes been added to SULib which allows 
programs to communicate with the shell and with other programs. 
Three basic mechanisms are provided. 


0 Set Next Run Command. fA procedure is provided which allows a 
program to tell the Workshop shell what to run next. The 
specified program will be run next (after the current program is 
done), taking precedence even over an exec file in progress. 


o The Program Return String. A string is provided which can be 
set programmatically and which can be accessed from the exec 
processor (via the RETSTR function). This allows exec scripts to 
be written which make choices based on program results. 


0 The Communication Buffer. A 1K byte buffer (global to the 
Workshop) has been provided for communication between 
programs. The buffer can be used in any number of ways; 
however, a set of primitives supporting character and 
line-oriented I/O to and from the buffer is provided. 


Note that the above mechanisms can be used in conjunction with 
each other. For example, @ program could write a series of 
invocation arguments to the communication buffer and then tell the 
shell to run a particular program next (via the set-next-run 
command). That program could then know to check the 
communication buffer to find its arguments. (In general, programs 
might be written so that they check the communication buffer for 
their arguments first and prompt for arguments from the console 
only if the arguments are not found in the buffer). 


The Details. 


The following describes the interface to the ProgComm unit. The 
following procedure initializes the ProgComm unit so that a program 
may use it. 


PROCEDURE PCinit; 
PCInit should be called before using the ProgComm unit. One 
effect of note is that the program's return string (RETSTR in 
the exec language) is initialized to the null string. 


The following two procedures give a program the ability to set what 
program will run next and to pass back a return string to the exec 
processor. Note that the SUStr type comes from the "standard unit” 
-- StdUnit in SULib -- which provides, arnong other things, @ number 
of string manipulation routines. 


PCSetRunCrnd (RC : SUStr} 
PCSetRunCmd enables a program to tell the shell what 
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program (or exec file) to run after the current program 
terminates, which allows program "chaining". RC, the run 
command you pass to PCSetRunCmd, should be a string with 
the same program pathname or exec file invocation you would 
give in response to the Workshop Run command prompt. The 
run command set in this way will take precedence over any 
keyboard type-ahead and over any pending exec file 
commands. 


There is an added complication when you want to use 
PCSetRunCmd to run a Workshop tool that is normally invoked 
from the Workshop menu line. (Note that only some of items 
in the Workshop menu are actually separate tools which can 
be "run".) The complication arises from the fact that typing 
'E' to invoke the editor is not always the same as typing 'R’ 
for run and specifying ‘editor.obj' as the program to run. The 
difference is that the Run command will look for ‘editor.obj' 
using the three level of prefixes, while the 'E' menu command 
will look on the Workshop boot volume first and then at the 
three prefix volumes. If you want to get the effect of the 
menu command, your argument to PCSetRunCmd should be a 
two character string with an escape (CHR(27)) as the first 
character and the appropriate menu command as the second 
character. 


Another subtlety, which you are unlikely to run into unless you 
.ere doing tricky things with exec files, is that starting to run 
an exec file while you are already running another exec file 
will cause the first exec file to be terminated in order to 
allow the second to be run. This means that if you run 
program P from exec file A, and P calls PCSetRunCmd to run 
exec file B, then, when program P terminates, exec file A will 
also be terminated so that exec file B can be run. Exec file 
A will not be resurned when exec file B has completed. This 
is another instance of the "exec file chaining" effect. 


PROCEDURE PCSetRetStr (RS : SUStr} 
PCSetRetStr allows a program to set 4 return string which 
may be accessed via the exec processor's RETSTR function. 
This allows exec files to make choices based on information 
passed back to the shell by cooperating prograrns. How the 
return string should be used and interpreted is up to you, and 
will depend on what sort of information you want to pass back 
to the exec processor. (But in order to be a good citizen it is 
probably best to follow whatever system-wide conventions 
emerge and prevail.) 


The following procedures and functions operate on the communication 
buffer, which is a 1K byte buffer which is global to the Workshop 
shell (that is, it stays around between program invocations). The 
buffer can hold essentially any type of information, but a standard 
set of functions is provided for Pascal-like character or line-oriented 
access to the buffer. 


Following are some CONST, TYPE, and VAR declarations from the 
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ProgComm interface which relate to the communication buffer. 


CONST 

{ cornmunication buffer content types } 

PCNone =-1; ~ { nothing in buffer } 

PCAny = 0; { for PCReset to match any content type } 

PCText = 1; { text, as supported by pCGets & PCPuts } 

PCBufrMax = 1023; { max buffer index, ie, bufr is 1K bytes } 
TYPE 

PCBufrP = “PCBufr; { ptr to bufr } 

PCBufr = PACKED ARRAY [0_PCBufrMax] OF CHAR; 
VAR 

PCBulrPtr -: PCBufrP; { points to bufr after successful open } 


The communication buffer is given a type when it is opened for 
writing with PCReWrite. This type will be used to determine 
whether a potential reader trying to open the buffer with PCReset 
will be successful. The intent is to prevent reading of the buffer 
when the contents are not of the type expected by the reader. Three 
predefined constants are provided for buffer typing: PCNone means 
that the buffer has no contents; PCText means that the buffer 
contains standard text with CR line delimiters; and PCAny matches 
any type, allowing a reader to override the typing mechanism. Other 
buffer content types (such as mouse events) may be defined users, 
choosing some number to identify the new type which does not 
conflict with the predefined types. We make no attempt here to 
provide a complete set of predefined types; the issue is simply one 
of having compatible conventions (agreement) between communicating 
programs. To use the buffer for something other than text, the 
variable PCBufrPtr may be used to access the buffer (using whatever 
means of interpretation of the buffer is desired). 


The buffer also has an access key, which functions in very much the 
same way 6s the content type (i.e., writers set it and readers must 
match it to gain access to the buffer). The intent of the access key 
is to prevent programs from reading the buffer when they sare not 
the intended recipient. The access key, again, is something that 
should be established by agreement between the communicating 
programs. If a buffer writer does not care about preventing 
unintended access to the buffer, the null string can be used for the 
access key. Note that the access key is case sensitive. 


Following are the procedures and functions which open and close the 
communication buffer. 


PROCEDURE PCReWrite (WriteType: INTEGER; Key: SUStr) 
PCReWrite opens the communication buffer for writing. The 
content type and access key are set. PCBufrPtr is set to 
point to start of the communication buffer. A PCReWrite will 
override any previous use of the buffer, i.e., it will flush any 
previous buffer contents. WriteType should be an integer 
identifying the type of data you plan to write to the buffer. 

If you are planning to use the text-oriented primitives ~ 
provided, WriteType should be PCText; otherwise, WriteType 
should be sore integer established by agreement between the 
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communicating programs. Key should be a string also 
established by agreement between the communicating 
programs. A useful form of key is one that identifies the 
intended recipient, so that things that get left in the buffer do 
not get read inadvertently by programs for which they were 
not intended. 


FUNCTION PCReset (ReadType: INTEGER; Key: SUStr: BOOLEAN, 
PCReset opens the buffer for reading. The boolean result will 
indicate whether the open was successful. The open will fail 
if ReadType does not match the type set by the last buffer 
writer or if Key does not match the key set by the last 
writer. 


FUNCTION PCClose (KillBufr: BOOLEAN, Key: SUStr: BOOLEAN; 
PCClose will close (or empty) the communication buffer. If 
KillBufr is true the buffer will be emptied. In general, the 
buffer can be read more than once (by multiple readers) if 
desired. If a reader is finished with the buffer and knows that 
no one else should read the buffer, PCClose should be called 
with KillBufy set to true. The call to PCClose will fail if the 
access key does not match. Note that PCClose may be used 
to flush buffers that were written by someone else, as long as 
you know the access key. PCClose may be called without 
calling PCReset or PCReWrite first. 


The following functions provide a text-oriented buffer facility with 
Pascal-like character and line-orierted reads and writes. 


FUNCTION PCPutCh (Ch: CHAR}: BOOLEAN; 
PCPutCh will put a character into the buffer. The boolean 
result will indicate whether the operation was successful. It 
will fail if the buffer is full or if the buffer was never opened 
successfully for writing. Note that PCPutCh{(CR) is equivalert 
to PCPutLine{"'). 


FUNCTION PCGetCh (VAR Ch: CHAR}: BOOLEAN, 
PCGetCh will get a character from the buffer. The boolean 
result will indicate whether the operation was successful. It 
will fail if the buffer is empty or if the buffer was never 
opened successfully for reading. 


FUNCTION PCPutLine (L: SUStr: BOOLEAN, 
PCPutLine will put a line into the buffer. A CR is put in the 
buffer following the string passed to PCPutLine. The boolean 
result will indicate whether the operation was successful. It 
will fail if the buffer is full or if the buffer was never opened 
successfully for writing. 


FUNCTION PCGetLine (VAR L: SUStr}: BOOLEAN; 
PCGetLine will get a line from the buffer, where a line is the 
text from the current buffer pointer up to the next CR or the 
end of file (whichever comes first). The boolean result will 
indicate whether the operation was successful. It will-fail if 
the buffer is empty or if the buffer was never opened 
successfully for reading. 
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You will notice the following function in the ProgComm interface; it 
is used for special-purpase communication between the Workshop 
shell and various Workshop tools. 


FUNCTION PCShellCmd (Cmd: INTEGER; P: SUStrP} BOOLEAN, 
For internal use by Workshop development system tools only. 
Contact me if you have a need to know about this function. 
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Release 3.0 Notes 
CHAPTER 2 THE FILE MANAGER 


Overview of Changes to the File Manager 
The sianificant changes to the File Manager involve: 


= The Operating System's new hierarchical catalog structure. 
« Transfer operations onto more than one micro diskette. 

» Pessword protection. 

« The new OS device narnes. 


The Opersting Systern uses new physical device names, but still supports the old 
names 6: device aliases. You can specify a device using either the narne or the 
alias; the OS refers to devices by name. The new names are: 


Name Alias Device 

#10F1 RS232A Serial Port A 

#10F2 RS2Z326 Serial Port B 

#11 FARAPORT Parallel Connector (Lisa 1) 

#12 UPPER or PARAPORT ~ Built-in hard disk (Lisa 2) 

#13 LOWER Micro diskette drive 

#1531 ALTCONSOLE Alternate consale 

#ISFZ MAINCONSOLE Main console 

#X SLOTX Peripheral at expansion slat x 

Hx Fy SLOTx CHANY Peripheral at expansion slot x, connector y 

#x#y#z SLOTxCHANYDEVz Peripheral at expansion slot x, conmector y, 
device Zz 


AddCatalog Command 
Files on a volurne can now he arranged under catalogs and subcatalogs. The 
AddCatalog command lets you create new catalogs. The pathname you specify for 
a catalog should refer to a volurne that has been initialized using the Release 3.0 
software. 


The Averenr is the catalog delirniter, so 6 file name referring to & file in & catalog 
might look like "-vol-cat-file" or "-vol-cati-catz-file", and so on. A file name of 
the forrn “cat-file" is interpreted relative to the current prefix and thus right refer 
to "-vol-cat-file" or “-vol-cati-cet-file"’, depending on whether the prefix is set to 
& volurneé or to 4 catalog. A catalog specified by a pathnarne without 8 volume 
pert will be created using the current main prefix. 


There is na special comrnand to put 4 file in a catalog. Once 6 catalog has been 
created, new files get put into it in two ways: 
1. If the new file’s narne is specified by « full pathnarne with volume and catalog 
parts, the file is put in the specified catalog. (A catalog rnust exist before s 
file can be put into it.) 
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2. If the new file's name is 4 partial pathnarne without & volume part, and the 
current prefix is & catalog, the file is put in the prefix catalog (or 6 
subcatalog, if the file's pathname includes & catalog part). 


When the OS tries to find a file given & partial pathname, the file will be found 
only if (1) the pathname has no catalog pert and is located in the prefix volume or 
catalog, or (2) the pathname has a catalog part corresponding to a path starting 
with a catalog at the top level af the prefix volume or catalog. 


Backup/Copy/Transfer to Multiple Micro Diskettes (See Sections 2.3.1, 2.3.2, and 2.3.7) 
The Backup, Copy and Transfer cornmands now allow backups, copies, and trenefers 
to multiple volurnes. If @ list of files is being copied {or backed up, or transferred) 
ta & micro diskette and you run out of space. you will be told which file didn't fit 
and how mary more blocks were needed, and you will be asked whether you want ta 
continue on another diskette. If you antwer Yes, you will be led through 6 diskette 
change and the operation will continue. Note that the volurne narnes of the 
subsequent diskettes need not match the first, ever if the original destination was 
specified with & particular volume name (instead of a device name). 


List and Names Commands (See Sections 2.3.4 and 2.3.13) 
There are two new attributes for iterns in the List display. The D attribute 
indicates a directory (a catalog object) and the * attribute indicates a6 
password-protected file (see Password Protection, below). 


The List and Narnes commands now indent names to show the catalog structure 
whenever you list a contiguous set of files. If you specify a wildcard character 
followed by a4 string to match, the files shawn will not necessarily be contiguous, 
and will not be indented. 


When a file narne has to be truncated to fit into a limited field of the display (as 
in the List command), the missing characters are now indicated by an elipsis (...). 


Prefix Command (See Section 2.3.5) 
Prefixes may now be set to catalogs im addition to volurnes. A prefix ta 6 catalog 
or subcatalog rnust be specified with a complete pathname. 


The effect of the current prefix on the interpretation of file narnes is discussed 
under AddCatalaog Command, above. 
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WARNING 


Setting the main prefix (or working directory) ray cause problems when 
running programs that use intrinsic units (this includes all the Workshop 
tools). The OS loader tries to find 6 prograrn’s intrinsic libraries using the 
pathnarnes it finds in INTRINSIC.LIB; if these names are partial pathnames, 
it looks on the prefix volurne or catelog, aot the soot volume To assure 
that your program's intrinsic libraries are found, you can do one of two 
things: 


1. Copy the intrinsic libraries ta the prefix catalog. This way, you can 
support several different library environments on the sarne volume, 
though you could end up with a proliferation of library files. 


2. Change the names of the libraries in INTRINSIC.LIB to pathnames of the 
form "-#BOOT-libnarne” (using the IJManager, described in Chapter 11, 
Utilities), then reboot so the OS will store the new names. This rnethod 
ig better, but be careful changing things in INTRINSIC.LIB. 


If you unmount the main prefix volurne by ejecting the diskette, Scavenging the 
Volume, or using the Unrnount command, the baot volurne becomes the prefix 
volurne. 


Rename Command (See Section 2.3.6) 
Toa rename 4 file to a narne thet only differs frorn the original in the case of the 
letters fe.g., DEMOGRAPHICS.OBI ta DernoGraphics.Obj), you rust first Rename the 
file to 4 ternporary name, then Renarne that to the name you want. 


Password Protection (See Section 2.3.10, FileAttributes) 
Two new carnmends for password protection are found under the FileAttributes 
command. AddPassword allows you ta password-protect a file (or files, using 
wildcards). RernovePassword allows you to remove a file's password, but you must 
know the password to remove it. 


The Workshop tools can't open a file once it is password-protected- you must 
remove the password before you can use the file. 


Initialize Command (See Section 2.3.11 and 2.4.1) 
Volurnes initialized under the new Workshop and OS have a hierarchical catalog 
Structure. Since this structure cannot be applied retroactively, an existing volurme 
must be reinitialized in order to take advantage of these features. Cornrnands that 
operate on a list of files (e.g, List) run much faster on 6 reinitialized disk, because 
in the new structure names ere already sorted. 


Online Command (See Section 2.3.14) 
The Online cornmend now displays both the new OS device names and the old 
names, which are now device aliases. The new device names are listed in the 
Overview at the beginning of this section, and shown in the syntax diagrarns under 
File Specifiers, below. 
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The prefix attribute P is now sometimes displayed as a lowercase p. Uppercase P 
indicates that the rrain prefix is the indicated volume. while lowercase p indicates 
that the prefix is 6 catalog on that volurne. 


NOTE 


The Online command uses the configuration information set oy Preferences. 
If Online cutput says thet it could not find #11 (PARAPORT) on a Lisa 2/10, 
use Preferences to detach the non-existent device. If the Workshop pauses 
unexpectedly in the middle of Online output, it means & device is configured 
but not present. Make sure that Preferences’ idea of how the system is 
configured is correct. 


File Specifiers (See Section 2.4.2) 
File specifiers have changed to allow for subcatalogs, new device names, and the 
new wild card characters. The diagrams that follow show the new format of file 
specifiers, replacing those on pages 2-9 and 2-10 of the manual. (The logical 
device narnes have not changed, but the diagram is repeated here for convenience.) 


<ART> syntax diagrams: file-specifier, 
file-name-or-pattern, 
volurne/catalog-spec, 
physical-device, 
physical-device-name & -alias, 
logical-device, 
wild-card-spec. 


New # and é Wildcard Characters (See Section 2.5) 
Because of the new hierarchical catalog structure, the mneanings of the = and ? 
wildcard characters have changed. and the new analogous wildcards # (OPTION =) 
and ¢ (OPTION 7} have been added. The plain = and 7 wildcards rnean search for a 
match only across the top level of the catalog, while the option wildcards mesn 
search through all levels. The way in which the matches are rnade is the same: 


= metches any string in the top level of the catalog. 
# matches any string throughout all levels of the catalag. 


?’ matches any string in the top level of the catalog, asking for confirmation of 
each file name before performing the operation. 


matches any string throughout all levels of the catalog, asking for confirmation 
of each file name before perforrning the operation. 
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file-name-or-pattern 
logical-device 
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file-name-or-pattern 


volume/catalog-spec 


volume/catalog-spec 


=O 
physical-device 


wild-card-spec 


a -O~ 


physical-device 


- physical-device-narne TY 
physical-device-alias 


physical-device-name physical-device-alias 
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(The device names on the left correspond to the device aliases on the right} 
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wild-card-spec 
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I-Code Definition 


The first pass of the conn ler generates 8 .I file. Its contents are 
described in this document . Please note that this information is likely to 
enenge without notice; there is no guarantee that it is correct. 


Ne ie Su, Abbreviations: = 
gas o expr => expression ejathn 4d Ae 
es . A addr => address QV) = \bb bis oak 


Ht => size of operand is 4 word 


sae (B) => size of operand is a byte 
ee | J 
00 vues A Aare Zot Be 
Variable references: 
O1 +offset(W) Global variable reference 
02 +offset(W) Local variable reference 
03 lev(B) +offset(W) Intermediate level variable reference 
yg 04 com(B) +offset(W) Comnon variable reference 
~~ OS ds 0(B) Register reference 
or 05 reg(B) loadSize(B) expr 


or 05 reg(B) loadCount(B) loadSize(B) expr 
reg=register number (0..15) 
/loadCount=number to bump count by (only significant with temp 
| registers) 
O=none (last use of reserved register) 
| l=sustaining use or first&last use 

- D 2=first use and reservation for future use 

_loadSize=size of expression to load register with 


\ QO=no load 
| =byte 
| =word 
3=long 
06 PPT TTT e ver —Stringtemp 
07 2272929 Ue A 
O8-0B Multiple Bytesize 1/2/4/8 byte temp {09=>2 byte operand} 
OC addr '*"  — Dereference operator 
OD addr '*" = File dereference operator 
OE addr "** — Text file dereference operator 
OF +offset(W) addr '.' = Record field offset 


pete Wordsize addr expr 


- 
— 
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1/2/4/8 byte array index 
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14 Wordsize Wordsize addr expr ify. - Long array index 
15 Bytesize Wordsize addr expr ‘[]' - Packed array access 


16 addr ‘@' - Address of operator 
(Constants: | 
17 nil 
ZY -18-1B Multiple ae. 1/2/4/8 byte constant {19=52-1yteSperandy 
vy IC stringSize(B) ' ..' String constant 
/ ID stringSize(B) ‘ ABC...' PROC Constant 


1E setSize(B) 
for 1 to bytesize do 
getnextoperand(B) Set constant 
1F {] - Null set 


\ Assignment operators: 


20-2f flippable(B) addr expr ‘i=! - 1/2/4/f byte assignment 


Flippable is tame if the ics ella left hand side can be computed 
after the right hand side. If true, We-have expr addr. 


20-22 2(B) addr expr Binary in-line assignment of byte/word/long 
expression. Evaluate addr, then expr, then assign 
Value of expr to location addr. Return expr. 


20-22 3(B) expri addr expr2 Triple in-line assignment of byte/word/long 
expression. Evaluate expri, then addr, then 
exprzZ, then assign value of expr2 to ‘ocekon 
addr. Return expri. 


Zo WOE 3 
. 24 Bytesize wardeize a expr =' - Multiple byte assignment 
Ne 2 4 2 addr expr ‘:=' — Set assignment 
Ree 26 1 tesize 2ndBytesize Wordsize 
‘ if istBytesize =21 then {PCKDARR} 
addr expr expr 
else 
Bytesize expr expr ':=' — Packed assignment 
27 Bytesize addr expr ':=' - String assignment 
28 Bytesize Bytesize addr expr a ~ PADC Assignment 
29 Bytesize addr expr ‘:m+' — Add to 
2A Bytesize addr expr ‘:s+' — Subtract from 
2B Bytesize WITH field reference, level nnn 


2C lev(B) isptr(B) a Begin WITH statement, level nnn 
2D lev(B) CX End WITH statement, level nnn 
2E 1 eH h (W) expr 2 Byte Range Check 

2F hi-( oe (H) String Range Check-assignment, not index 
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30-32 expr 
33-35 expr 
36-37 expr 
38-39 expr 
3A-38 expr 
3C-3D expr 


3E Bytesize expr 
3F Bytesize expr 


(Scaler operators: ) 


K 


40-41 
42-43 
44-45 
46-47 
48-49 
4A-4B 
4C-4D 
4E~4F 
30-52 
33-55 
36-58 
39-568 
3C-5E 
IF-61 
62-64 
65-67 
66-6A 
66-6D 

6E 

6F 
70-71 
742-73 
74-75 
16-77 
78-79 
7A-7B 
70-70 
7E-7F 
30-81 
82-83 
84-85 
86-87 
88-89 


expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 


| Data Conversion i 
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expr 
expr 
expr 
expr 
expr 


expr 
expr 
expr 


expr 
expr 
expr 
expr 
expr 
expr 


expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
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1->2, 2->4, 1->4 integer 
2->1, 4->2, 4—>1 integer 
4->8, 6->4 real conversion 


4->4,4->8 Float 
4-)>4,8->4 Trunc 
4->4, 8>4 Round 


Extract unsigned field 
Extract signed field 


2/4 Scalar Addition 

2/4 Scalar Subtraction 
2/4 Scalar Multplication 
2/4 Scalar Division 

2/4 Scaler Modulus 


2/4 Scaler Negate 


2/4 Scalar Absolute Value 


2/4 Scalar Square 
1/2/74 Scalar AND 
1/2/4 Scalar OR 
1/2/4 Scalar XOR 
1/2/4 Scalar NOT 
1/2/4 Scalar < 
1/2/4 Scalar > 


1/2/4 Scalar 


1/2/4 Scalar 


< 
1/2/4 Scalar > 
1/2/4 Scalar < 


Boolean NOT 


OQDD 

4/8 Real 
4/8 Real 
4/8 Real 
4/8 Real 
4/8 Real 


4/8 Real 


4/8 Real 
4/8 Real 
4/8 Real 
4/8 Real 
4/8 Real 
4/8 Real 
4/8 Real 


Addition 


Subtraction 
Multiplication 


Division 
Modulus 
< 


> 
< 
> 


<> 
Negation 


Absolute Yalue 
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Strin Operators 


g 
90 expr 
91 expr 
92 expr 
93 expr 
94 expr 
95 expr 


96 stringsize(B) 
97 stringsize(B) 
98 stringsize(B) 
99 stringsize(B) 
9A stringsize(B) 
9B stringsize(B) 


oC 4 
2 | 
| 
OF y) 
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i Set Operators? 
ort 


expr 
expr 
expr 
expr 
expr 
expr 


8 ekg, 


AO setsize(B) 


Rl sets 


ize(B) 


AZ setsize(B) 


AS sets 
A4 sets 
ADS sets 
AG sets 
A? sets 
A8 sets 


ize(B) 
ize(B) 
ize(B) 
ize(B) 
ize(B) 
ize(B) 


AI setsize(B) 
AA setsize(B) Bytesize expr Adjust Set 
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expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 


expr 
expr 
expr 
expr 
expr 
expr 
expr 
expr 


expr 


4/8 Real Square 
TRAPY 


String < 
string > 
String <= 
String >= 
String = 
string <> 


stringsize(B) expr expr PAOC < 
stringsize(B) expr expr PROC > 
stringsize(B) expr expr PAOC < 
stringsize(B) expr expr PAOC > 
stringsize(B) expr expr PAOC = 
stringsize(B) expr expr PAOC < 


Set + 
Set - 
Set * 


< 
Set > 


Set <> 
Singleton Set 
Set Range 
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( Procedure/Function Calls: / 


B? 
>) BB-BB 


index(W) 
index(W) 
key(B) 
key(B) 

addr 

addr 

room(B) 

addr 

expr 

size(W) expr 
setsize(B) expr 
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User Function Call 

User Procedure Call 

Standard Function Call 
Standard Procedure Call 
Parametric Function Call 
Parametric Procedure Call 
Make Room for Function Result 
Reference Parameter 

1/2/4/8 Byte Value Parameter 
Large Value Parameter 

Set Value Parameter 

Begin Parameter List 

User Function/Procedure Parameter 


BF index(W) 


Control: ) 

CO label (W) 

C1 label(W) 

C2 label(W) expr 

C3 label(W) expr 

C4 usernum(W) label(W) 

C5 peat label(W) linknum(W) 

C6 usernum(W) label(W) 

C7 lev(B) linknum(W) 

C8 expr 

C9 0(B) lobound(W) hibound(W) 
elseLabel(W) loLabel(W) hiLabel(W) 
1(B) lobound(W) hibound(W) 
elseLabel(W) count(W) 
{[value(W), label(W)] 
CA ctrsize(B) addr expri expr2 expr3 


at C9 


Define Internal Label 
Jump 

Jump False 

Jump True a 

Define Local User Label 
Define Global User Label 
Jump to Local User Label 
Jump to Global User Label 
Case Jump 


Case Table--must follow case jump 


If expr list—must follow case jump 
FOR statement 


ctrsize - size of loop counter (1, 2, 4) 


addr - counter 
expril - start 
expr2 -—- end 
expr3 -—- increment 

CB 

CC 

CD linenum(W) 


or if linenum = -1 then 
CD -1(W) length(B) fileneme 
~CD -2(W) bool(B) 
CE regset(W) 
regset=set of register (0..15) 
bit on=reserve register 


FOR end 
CASE end 
Line number 


To open an INCLUDE or USES file 
Rssembly listing control switch 
Temp registers mask 


bit off=make register available for codegen temp use 
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CF 
DO--DF 
EO--EF 


FO fin) (un) (cfn} (sn) fnsw 
lev(B) varsize prmbyts 


glb regmask Begin Module 
{1n) - 8&byte Linker neme 
(un) - &byte User neme 
(cfn) —- &byte class father neme 
(sn) - &byte Segment name 
fnsw - function switch (fn or proc) = 
lev ~ level (1=global)} 


varsize -— Number of bytes of local variables 
prmbyts - Bytes of parameters + 8 
glb ~ Global Label Flag is Bit 0 
Stack Expan. Flag is Bit 1 

regmask - register mask for MOVEM 

Fi (1n) (un) num(W) levi(B) External Reference Definition 

F2 (1n) num(B) kind(B) Common Reference Definition 

F3 (cn) nonnnnn Common Area Definition 

F4 (un) Bytesize textaddr4(W) Bytesize Bytesize textsize4(W) Bytesize 

globsize2(W) untType(B) Unit File Header 
~~ F5-FB 

FC fn(B) size(W) const(W) In-line function switch 

FD fn(B) level(B) method(B) Method call 

FE debugflag(B) End of module (D compiler option) 

FF End of file 
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Feb. 22, 1984 
New I-codes for Optimization 


Tne I-code changes and new I-codes for the current optimization project 
include: 


- Code Name Operands Definition 
$05 Register Reg LoadCount LoadSize Expr... Register reference. 


(B) (B) (new!) = (B) 


Reg=register number (0..15) 
Loadcount=number to bump ‘count’ by (only 
significant with temo registers): 
= none (last use of reserved register) 
1 = sustaining use or firsté&last use 
2 = first use and reservation for future use 
LoadSize=size of expression to load register with. 


0 = no load. 
1 = byte. 
2 = word. 
3 = long. 
$CE TemoStmt le Temp Registers Mask. 
(W 


Regset=set of register (0..15) 
bit on = reserve register 
bit off= make reg available for codegen temp use. 


Binary Inline Assign's: 


$20 2 Addr... Expr... Inline assignment of byte expr. 

$21 2 Addr... Expr... Inline assignment of word expr. 

$22 2 Addr... Expr... Inline assignment of long expr. 
B 


Evaluate “addr", then "expr", then assign value of “expr” to 
location “adar". Return “expr”. 


Triple Inline Assign's: 


$20 3 Expri... Addr... Expr2... Inline assignment of byte expr. 

$21 3 Expri... Addr... Expr2... Inline assignment of word expr. 

$22 3 Expri... Addr... Expr2... Inline assignment of long expr. 
(B) 


Evaluate "expri", then "addr", then "expr2", then assign value 
of "expr2" to location "addr". Return "“expri”. 


